haskell-servant / haskell-servant/servant

Expose some information about API resolution to middlewares

Open
#1,553 1 comment 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.