GitHub

http_api

API reference for http_api.

Typed HTTP APIs (Effect's effect/http-api): declare endpoints once, serve them, call them with a derived client and document them with OpenAPI.

  • endpoint: get / post / ... make an HttpApiEndpoint from its path and the schemas of its params, query, payload, headers, successes and errors
  • group: HttpApiGroup, a class whose attributes are endpoints
  • api: HttpApi, groups under one identifier
  • builder: group(api, Users, build) is the layer of a group's handlers, layer(api) adds every group's routes to the router
  • client: make(api) derives a client whose methods are typed by the declarations; test: one calling the handlers in memory
  • schema: response statuses, encodings, streams (SSE, NDJSON, bytes), upgrades and response headers; error: the status errors
  • middleware, security: HttpApiMiddleware and the credentials it decodes (bearer, basic, API keys)
  • openapi: the OpenAPI 3.1 document of an API; swagger and scalar serve it as documentation pages

::

class Users(HttpApiGroup, identifier="users"):
    get_user = endpoint.get(
        "getUser", "/users/:id", params=S.Struct(UserParams), success=User, error=NotFound
    )

api = HttpApi.make("app").add(Users)
UsersLive = builder.group(api, Users, lambda h: h.handle(Users.get_user)(get_user))
api_client = yield from client.make(api)
user = yield from get_group(api_client, Users).get_user(params={"id": 1})

Re-exports

Classes

Modules