Thank you for all the hard work on effect and the HttpApi module. So far I refactored three internal APIs and built a cart API with it and in general it's a joy to work with it.
What I really love about it: We can generate 90% of our needed glue code from the api definition. Currently we are deriving all infrastructure IaC (CDK / AWS) from it as well as contract tests, which really pays off, as the api definition became the single source of truth.
There are two pain points though that I have encountered and I wondered if there might be a better way to handle them or I might have missed something.
1. Error handling
Our cart API reaches out to some effectful services, that already return
S.TaggedErrors
S.TaggedErrors
with an
HttpApiSchema
HttpApiSchema
status annotation. Still I have to explicitly redeclare all possible errors on the API definition.
For complex dependency graphs, this feels cumbersome. From my perspective there are three types of errors/developer intents:
- Expected Errors without an Http Status ("internal / private errors") - Expected Errors with an Http Status ("public" errors, that a client can react upon) - Defects
If I declare an error with an http status (with an HttpApiSchema annotation), IMHO I express the intent that this error might go over the wire. Ideally I would not need to add these errors to the API explicitly, or at least have the option not to do so. Additionally some way to catch only "non-specified" errors would be nice, so I can transform them to a
500 ServerInternalError
500 ServerInternalError
or something alike.
Does this make sense?
2. Headers
It would help ergonomics if we could add headers to whole groups / apis. We have multi-tenant services where users can impersonate different tenants, so we require a "tenant-id" header in each api call. Currently I need to add this header to every endpoint (which is error-prone / easy to forget).