diff options
| -rw-r--r-- | api-conventions.md | 212 | ||||
| -rw-r--r-- | paste.sr.ht/api.md | 97 | ||||
| -rw-r--r-- | paste.sr.ht/index.md | 7 | ||||
| -rw-r--r-- | paste.sr.ht/installation.md | 4 |
4 files changed, 320 insertions, 0 deletions
diff --git a/api-conventions.md b/api-conventions.md new file mode 100644 index 0000000..8e12303 --- /dev/null +++ b/api-conventions.md @@ -0,0 +1,212 @@ +# API Conventions + +Each sr.ht API follows the same set of design conventions throughout. Each API +is RESTful, authenticated with [meta.sr.ht](meta.sr.ht), and has consistent +standards for pagination, response codes, and so on, throughout. + +## Authentication + +All services are authenticated with OAuth via meta.sr.ht. For more information, +consult [the meta.sr.ht OAuth documentation](meta.sr.ht/oauth-api.md). + +## 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`. + +OR + +A singleton which is owned by `:resource`. + +OR + +A named action to be completed asyncronously. + +### /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: + +```json +{ + "next": :id, + "results": [ :resources... ], + "results_per_page": 50, + "total": 200 +} +``` + +To retrieve the next page of results, add `?get=: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: + +```json + { + "errors": [ + { + "field": "example", + "reason": "example is requried" + } + ] + } +``` + +`"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. + +**Response** + +```json +{ + "version": "1.2.3" +} +``` + +## 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`. + +### Subscription resource + +```json +{ + "id": integer, + "created": "timestamp", + "events": ["event", ...], + "url": "subscription URL" +} +``` + +### Delivery resource + +```json +{ + "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** + +```json +{ + "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 + +**Response** + +The new subscription resource. + +### GET /api/.../webhooks + +List of subscription resources. + +### GET /api/.../webhooks/:id + +Retrieves a subscription resource. + +### GET /api/.../webhooks/:id/deliveries + +List of delivery resources for this subscription. diff --git a/paste.sr.ht/api.md b/paste.sr.ht/api.md new file mode 100644 index 0000000..760fd45 --- /dev/null +++ b/paste.sr.ht/api.md @@ -0,0 +1,97 @@ +# API Reference + +The paste.sr.ht API allows you to browse and create pastes on paste.sr.ht +programmatically. This API follows the [standard sourcehut API +conventions](../api-conventions.md). + +## Authentication + +Authentication is done via the [meta.sr.ht OAuth +flow](https://man.sr.ht/meta.sr.ht/oauth-api.md). The following OAuth scopes are +available for paste.sr.ht: + +- **paste:read** & **paste:write**: read & write pastes + +## Resources + +### Paste resource + +```json +{ + "created": "timestamp", + "sha": "id of this paste (SHA-1 hash)", + "user": { short-form user resource }, + "files": [ + { + "filename": "filename" or null, + "blob_id": "id of this blob (SHA-1 hash)" + }, ... + ] +} +``` + +### Blob resource + +```json +{ + "created": "timestamp", + "sha": "id of this blob (SHA-1 hash)", + "contents": "contents of this blob" +} +``` + +## Endpoints + +### GET /api/pastes + +List of paste resources. + +**OAuth scope**: `pastes:read` + +### POST /api/pastes + +Create a new paste; + +**OAuth scope**: `pastes:write` + +**Request body** + +```json +{ + "files": [ + { + "filename": "filename" or null, (optional) + "contents": "contents of this file" + } + ] +} +``` + +- **contents** must be a UTF-8 encoded string; binary files are not allowed + +**Response** + +The new paste resource. + +### GET /api/pastes/:sha + +Retrieves a paste resource. + +### GET /api/blobs/:sha + +Retrieves a blob resource. + +## Webhooks + +### /api/pastes/... + +Webhook for paste events. Includes the [standard webhook +endpoints](../api-conventions.md#Webhooks) + +#### paste:create: + +Issued when a new paste is created. Requires `paste:read` OAuth scope. + +**Request body** + +Affected paste resource. diff --git a/paste.sr.ht/index.md b/paste.sr.ht/index.md new file mode 100644 index 0000000..18a207d --- /dev/null +++ b/paste.sr.ht/index.md @@ -0,0 +1,7 @@ +[paste.sr.ht](https://paste.sr.ht) is an ad-hoc text file hosting service on +sr.ht. + +**See also** + +- [API reference](api.md) +- [Installation](installation.md) diff --git a/paste.sr.ht/installation.md b/paste.sr.ht/installation.md new file mode 100644 index 0000000..fc9c122 --- /dev/null +++ b/paste.sr.ht/installation.md @@ -0,0 +1,4 @@ +# Installation + +paste.sr.ht is a standard sr.ht web service and can be installed through the +[standard procedure](/installation.md). |