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