haskell-servant / haskell-servant/servant
Expose some information about API resolution to middlewares
- Dominant language
- Haskell
- Stars
- 2k
- Forks
- 427
- Avg merge
- 2d 23h
- Merged PRs (30d)
- 5
Description
Recently, I tried to write a [WAI Middleware](https://hackage.haskell.org/package/wai-3.2.3/docs/Network-Wai.html) that was aware of the API my application was using. In particular, given an incoming request url, I wanted to be able to tell which endpoint was used, and which parts of the url were captured.
For instance, consider the server api below:
```haskell
type Api =
"foo" :> Capture "id" Int :> Get '[JSON, PlainText] Foo
:<|> "bar" :> Capture "id" Int :> Get '[JSON, PlainText] Bar
```
Let us request it with the following command:
```bash
curl -X GET "http://localhost/foo/12345" -H "Accept: application/json"
```
If the request succeeds, we should get a Foo object, encoded as JSON.
The additional data I would like to get from Servant for my middleware would be something like:
```json
{
"effective-url": "/foo/",
"content-type": "application/json"
}
```
The `"content-type"` part is easy to get from the response header, but the `"url"` part doesn't seem easily available.
Effectively, what I would need is a way to perform the transformation `GET "/foo/12345"` => `GET "/foo/"`
I can think of several ways for Servant to provide this information:
* Return the "effective type" that was used for each request, to be processed by the middleware. For instance, the request above would return
```haskell
type EffectiveApi = "foo" :> Capture "id" Int :> Get '[JSON] Foo
```
* Introduce a combinator that would have the effect of including routing information in the response headers. The API above would then be written as
```haskell
type Api = WithRouting :>
"foo" :> Capture "id" Int :> Get '[JSON, PlainText] Foo
:<|> "bar" :> Capture "id" Int :> Get '[JSON, PlainText] Bar
```
then the response headers would include `"Effective-Url": "/foo/"`
* Introduce a new `Servant.Middleware` that would be aware of API resolution mechanisms.
Contributor guide
Research direction
Start by reviewing Servant's API resolution mechanisms and the WAI Middleware integration described in the issue. Compare the proposed approaches for exposing the effective endpoint and captured URL parts, then identify the relevant routing and middleware entry points. Done should make the resolved route information available to middleware without requiring application-specific changes.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- haskell
- Domain
- api, backend-api-design
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100