Document Raw's behaviour when composing APIs

This commit is contained in:
bChiquet 2021-09-29 10:11:28 +02:00
parent bf160cc1ad
commit 29aa10176d

View file

@ -389,3 +389,30 @@ One example for this is if you want to serve a directory of static files along
with the rest of your API. But you can plug in everything that is an
`Application`, e.g. a whole web application written in any of the web
frameworks that support `wai`.
Be mindful! This library works by pattern-matching the different routes that are
composed using `:<|>`. `Raw`, as an escape hatch, matches any route that hasn't
been matched by previous patterns. Therefore, any subsequent route will be silently
ignored.
``` haskell
type UserAPI14 = Raw
:<|> "users" :> Get '[JSON] [User]
-- In this situation, the /users endpoint
-- will not be reachable because the Raw
-- endpoint matches requests before
```
A simple way to avoid this pitfall is to either use `Raw` as the last
definition, or to always have it under a directory.
``` haskell
type UserAPI15 = "files" :> Raw
-- The raw endpoint is under a directory,
-- so it won't match /users.
:<|> "users" :> Get '[JSON] [User]
type UserAPI16 = "users" :> Get '[JSON] [User]
:<|> Raw
-- The Raw endpoint is matched last, so
-- it won't overlap another endpoint.
```