Add paste.sr.ht docs & API conventions

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).