Serv is a collection of libraries for creating HTTP APIs. You construct a sophisticated, custom type which represents the structure of your API and then use libraries to construct servers, clients, and documentation which are statically guaranteed to conform to your specification.

type GetResponses = 
  ‘[Ok ::: Respond 
             '[Lastmodified ::: UTCTime]
             (HasBody ‘[JSON, TextPlain] User)]

type PutResponses = 
  '[Ok ::: Respond 
             '[Location ::: URI] 
             Empty]


type TheApi
  = Const “user” :> 
      Endpoint ()
      '[ GET ::: Outputs GetResponses
       , PUT ::: CaptureBody ‘[JSON, TextPlain] User 
                   (Outputs PutResponses)
       ]

This repo contains the 3 main existing Serv libraries:

• serv describes the API specification type language. It’s the basic dependency of all serv-* libraries.
• serv-wai is a tool for constructing (Wai-style) web servers which statically conform to serv API types.
• http-kinder provides detailed types and kinds representing headers, query parameters, status codes, and uri segments in HTTP requests. It also provides for encoding/decoding these pieces of the request as Haskell types.

Serv is heavily inspired by Haskell’s servant which also provides type-safe APIs. Unlike servant, Serv endeavors to provide an API specification language which is itself well-typed (or, really, well-kinded) and benefits in several ways for this choice. Serv is another point in a similar design space. Or, in bulleted list format:

• Serv's API language is kind-restricted enabling us to be more sure that API descriptions make sense and enabling us to write closed type functions over API descriptions with greater confidence that the function will not become stuck. On the other hand, servant has all API descriptions at kind * and therefore is more easily extensible.

• Serv's API language is also more regular than servant's. Again this is helpful for writing type functions to analyze API descriptions since they can pattern match on each path, api, and method component in the description.

• Serv's API language includes an explicit notion of an Endpoint and even listing of the Status codes which might arise whereas servant's is more implicit (though it could be extended to include this idea). Explicit Endpoints enable proper OPTIONS (and eventually CORS) handling in a way that's transparent to you, the library user.

Serv is still in early design phases. Contribution ranging from PRs to feedback on the API design language is very welcome. See the issues tracker to find interesting projects, submit new issues, or email me at mailto:me@jspha.com.