sr.ht-docs/api-conventions.md at master

7.2 KiB

Raw Permalink Blame History

title
API Conventions

Each sr.ht API follows the same set of design conventions throughout. Each API is RESTful, authenticated with meta.sr.ht, and has consistent standards for pagination, response codes, and so on, throughout.

API Wrappers

API wrappers for a few programming languages exist:

Please write to sr.ht-discuss to share yours!

Authentication

All services are authenticated with OAuth via meta.sr.ht. For more information, consult the meta.sr.ht OAuth documentation.

Routing

The basic routing model is:

/api/:resource

List of :resources, e.g. /api/repos

GET: retrieve the list
POST: create a new resource

/api/:resource/:id

Manipulate a specific :resource by :id.

GET: retrieve the resource
PUT: modify the resource
DELETE: destroy the resource

/api/:resource/:id/:subresource

List of :subresources which are children of :resource.

A singleton which is owned by :resource.

A named action to be completed asynchronously.

/api/:resource/:id/:subresource/:id

Manipulate a specific :resource by :id. See /api/:resource/:id.

Notes

The :id may be an integer or string

Request & response format

All requests and response bodies shall be encoded with Content-Type application/json.

Resource schemas

Each resource returned by the API has its own schema, and may be given in two forms: full form and short form. The full form is always returned when retrieving a resource by ID, and contains the maximum amount of detail. The short form contains less information — an ID at the minimum, but often more - and is returned where the long form would be inconvenient, such as from a list endpoint or for singletons embedded in a parent resource.

Timestamps

Timestamps are encoded as strings using the format %Y-%m-%dT%H:%M:%S.

Pagination

When executing a GET request on a list of resources, the response format is:

{
  "next": :id,
  "results": [ :resources... ],
  "results_per_page": 50,
  "total": 200
}

To retrieve the next page of results, add ?start=:id to your request URL, using the :id given by "next".

Response codes

The use of HTTP response codes is standardized throughout sourcehut.

200: Resource(s) found
201: Resource(s) created
202: Your request has been accepted and is processing
204: Used when resource(s) are successfully deleted
400: Your request is invalid (missing required fields?)
401: You're missing the (or have an invalid) Authorization header
403: You're not allowed to do what you're attempting
404: Resource(s) not found
5xx: Something broke on our end

Error responses

Errors are returned with a consistent response body:

  {
    "errors": [
      {
        "field": "example",
        "reason": "example is required"
      }
    ]
  }

"field" is omitted when it is not applicable.

Standard endpoints

GET /api/version

Returns the API version installed for this service. Sourcehut uses semantic versioning, each version being of the format "major.minor.patch". The patch number increments with every release, the minor number increments when new features are added, and the major version increments on breaking changes. Note that the minor and patch versions may increment when changes are made to the web frontend — which may not necessarily affect the API — but major versions only increment on breaking API changes. Any API whose major version is 0 makes no guarantees about interface stability.

Changes considered non-breaking are adding new API endpoints and resources, adding members to existing resources, adding members to enumerations, and adding optional fields to existing requests.

Response

{
  "version": "1.2.3"
}

Standard resources

User resource

full form

{
  "canonical_name": "~username",
  "name": "username",
  "email": "email",
  "url": "url" or null,
  "location": "location" or null,
  "bio": "bio" or null
}

short form

{
  "canonical_name": "~username",
  "name": "username"
}

Webhooks

Most resources will have webhooks which can deliver updates to your application via HTTP POST. You'll able to subscribe to some number of events, such as (on meta.sr.ht) profile:update or ssh-key:remove. These require the same OAuth scopes to configure as are necessary to obtain these resources through polling - there's no separate OAuth scope for webhooks.

Periodically polling the API is discouraged — use webhooks instead.

Webhook delivery

When the events you've subscribed to occur, the notification will be delivered to your URL as an HTTP POST, generally in the same format as the affected resource is encoded via the API. X-Webhook-Delivery is set to a UUID assigned to that webhook delivery, and X-Webhook-Event is set to the specific event that occurred, e.g. profile:update.

Webhook signatures

The X-Payload-Signature and X-Payload-Nonce headers can be used to verify the authenticity of the webhook payload. Concatenate the request body with the nonce (treat the nonce as an ASCII-encoded string) and use it to verify the base64-encoded Ed25519 signature given by the X-Payload-Signature header. The public key (also base64 encoded) is uX7KWyyDNMaBma4aVbJ/cbUQpdjqczuCyK/HxzV/u+4=. Here's an example of verifying the payload in Python:

import base64
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey

public_key = Ed25519PublicKey.from_public_bytes(
    base64.b64decode('uX7KWyyDNMaBma4aVbJ/cbUQpdjqczuCyK/HxzV/u+4='))

payload = request.data
signature = headers["X-Payload-Signature"]
signature = base64.b64decode(signature)
nonce = headers["X-Payload-Nonce"].encode()

public_key.verify(signature, payload + nonce)

Subscription resource

{
  "id": integer,
  "created": "timestamp",
  "events": ["event", ...],
  "url": "subscription URL"
}

Delivery resource

{
  "id": integer,
  "created": "timestamp",
  "event": "event",
  "url": "subscription URL",
  "payload": "request body",
  "payload_headers": "request headers",
  "response": "response body",
  "response_status": integer,
  "response_headers": "response headers"
}

response_status is -2 prior to delivery, and -1 if delivery failed.

POST /api/.../webhooks

Request body

{
  "url": "http://example.org/webhook-notify",
  "events": ["profile:update", "ssh-key:remove"]
}

url: the URL that should have webhook deliveries issued to it
events: the list of events this subscription should include