I spend some considerable time reverse engineering the module, so I
thought I’d write the documentation I would have liked to see.
The strategy here is that a user not necessarily has insight into how
servant works internally, or even how to write complex servant routes,
they just want to generate a list of endpoints and convert the `Req`
type into e.g. generated code in $language. Thus, they need to know
the semantics of all fields of Req, how they interact and how they
relate to a plain http route.
I made sure every `f` is replaced with `ftype`, so we have one
conventional way of referring to the foreign type argument everywhere.
Some enums are not set at all, they are marked as such.
`_reqBodyContentType` introduces a major restriction of the module, so
that is mentioned in the documentation for now, until the time it will
be fixed.
A few TODO’s describe places where types don’t make sense but would
introduce API-breaking changes, so these should probably be
simplified,
but bundled in one go.
- Introduce SourceT, which is simple variant of "correct `ListT`".
There are another variants possible (like in `streaming`),
but I'm not sure there's much real difference.
- Introduce `Codensity`. There's a flag if people don't want to depend
on `kan-extensions`.
- `StreamGenerator` and `ResultStream` are both `SourceT`.
`Stream` combinator in `servant-client` uses `Codensity` for CPS.
- Add servant-machines, servant-conduit, servant-pipes
- Add streaming cookbook: just code, no explanations.
- Add a script to run streaming 'benchmarks'
- Add Streaming endpoint to the comprehensive API.
- Rename BuildFromStream to FromResultStram
- I'm tempted to rename everything in the Servant.API.Stream
(add some prefixes, `header` is too good name to steal)
The TODO in `servant-docs` is left intentionally.
Changes Header, ReqBody and QueryParam to take a modifier list.
Resolves https://github.com/haskell-servant/servant/issues/856
ResponseHeader story turns to be somewhat ugly, but it can be made
elegant when https://github.com/haskell-servant/servant/issues/841 is
implemnted, then we can omit HList aka Header Heterogenous List
implementation.
- servant-server changes:
Writing server side intepretations is quite simple using
`unfoldRequestArgument`, which makes Header and QueryParam look quite
the same.
`ReqBody` cannot be easily made optional with current design (what that
would mean: No Content-Type Header?), so that dimensions isn't used
there.
- Add HasLink for all the rest ComprehensiveAPI combinators
- Add 'tricky' Header', QueryParam' endpoints to ComprehensiveAPI
- servant-docs: Quick'n'dirty implementation. Don't use modifiers information (yet).
We use NoContent to signify an empty response nowadays. This commit
replaces all occurences of () with NoContent so that all packages use
the new semantics.
We allow a user-specified type to represent the foreign type of haskell
types encountered in the API. This lets users map Integer, Date etc. to
representations other than Text, and have those representations
available in the returned list of Req.
For example, we might want to map a type which has an instance of
Generic to both a foreign type name and a class declaration for that
foreign type such that it can encode/decode itself to JSON. The previous
limitation to a single Text output prevented this case.
* non-messy imports
* got rid of most long lines (>80 chars)
* prisms for sum types and newtypes(we use lens anyway, so why not)
* consistent indentation
