Skip to content

endpoints.md

Latest commit

 

History

History
94 lines (76 loc) · 3.48 KB

endpoints.md

File metadata and controls

94 lines (76 loc) · 3.48 KB

Endpoints

endpoints: is a tree of URL paths. Keys starting with / are child paths; keys naming HTTP methods are method handlers at the current path.

endpoints:
  /users:
    get:  {sql: CALL UserList(), return: list}
    post: {sql: CALL UserAdd({args.name})}

    /{id}:
      args: {id: {type: u32}}
      get:    {sql: CALL UserGet({args.id}), return: dict}
      delete: {sql: CALL UserDelete({args.id})}

Path syntax

  • /literal — exact match.
  • /{name} — capture into args.name.
  • /regex.* — paths are regexes (RE2). Capture groups with {name} become args.

Methods

Lower-case method names: get, put, post, delete, options, head, patch. Combine with | to share a handler:

/.*:
  get|put|post|delete:
    handler: session

Use any for all methods.

Endpoint keys

Apply on any method or path block. Child keys (paths and methods) inherit from parent keys for args and allow/deny.

Key Purpose
handler Handler name. See handlers.md.
handlers List of handlers run in order (e.g. CORS + query).
sql SQL query. Implies handler: query.
query Name of a query defined in queries:. See sql.md.
args Arg definitions. See args.md.
allow / deny Access rules. See access-control.md.
headers Response headers, as a map.
return Query return shape. See sql.md.
into Capture a query result and continue. See sql.md.
reply Reply with a resolved value. See handlers.md.
steps List of statements run in order. A bare list body is shorthand. See exec.md.
fields Field layout when return: fields. See sql.md.
body Raw binary request body. See binary.md.
files Multipart file-part declarations. See binary.md.
content-type Response Content-Type for return: binary. See binary.md.
help Description used in the OpenAPI spec.
hide If true, omit from the OpenAPI spec.
exec Run an external program as a step. See exec.md.
if / then / else Conditional execution. See conditions.md.
path File path. Implies handler: file.
index Index filename for handler: file directories.
resource Compiled-in resource name. Implies handler: resource.
bind Name of a C++-bound callback. Implies handler: bind.
url Upstream URL. Implies handler: proxy.

Inheritance

args and allow/deny blocks defined on a parent apply to all children:

/users:
  allow: [$admin]            # applies to all child endpoints
  /{id}:
    args: {id: {type: u32}}  # applies to all methods under /{id}
    get:    {sql: ...}
    delete: {sql: ...}

Multiple handlers

Use handlers: to chain handlers (e.g. set headers then run a query):

/data:
  get:
    handlers:
      - {handler: cors, patterns: ["https://example.com"]}
      - {sql: CALL DataList(), return: list}