Add paste.sr.ht docs & API conventions

1 files changed, 212 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.