@@ -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! This library works by pattern-matching the different routes that are
394+composed using `:<|>`. `Raw`, as an escape hatch, matches any route that hasn't
395+been matched by previous patterns. Therefore, any subsequent route will be silently
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 directory.
409+type UserAPI15 = "files" :> Raw
410+ -- The raw endpoint is under a directory,
411+ -- 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.