Feedback on HttpApi Module
Hi Tim,
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.
Our cart API reaches out to some effectful services, that already return
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
Does this make sense?
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).
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.TaggedErrorsHttpApiSchemadefinition.
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 ServerInternalErrorDoes 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).
Similar Threads
Was this page helpful?
