diff options
| -rw-r--r-- | git.sr.ht/api.md | 298 | ||||
| -rw-r--r-- | git.sr.ht/index.md | 1 | ||||
| -rw-r--r-- | index.html | 2 |
3 files changed, 301 insertions, 0 deletions
diff --git a/git.sr.ht/api.md b/git.sr.ht/api.md new file mode 100644 index 0000000..e44e3cf --- /dev/null +++ b/git.sr.ht/api.md @@ -0,0 +1,298 @@ +--- +title: git.sr.ht API reference +--- + +The git.sr.ht API allows you to browse, create, and manage repositories on +git.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 git.sr.ht: + +- **info:read**, **info:write**: read & write repository details +- **access:read**, **access:write**: read & write access control lists +- **data:read**: read git data + +## Git protocols + +The high and low-level data endpoints are basic and provided as a convenience. +For write operations or more complex read operations, we recommend using the +git interface. git.sr.ht supports the [smart protocol][protocols] over HTTPS +(read-only) and SSH (read/write). + +[protocols]: https://git-scm.com/book/en/v2/Git-Internals-Transfer-Protocols + +## Resources + +### Commit resource + +```json +{ + "id": "sha-1 hash", + "short_id": "truncated hash", + "author": { + "email": "email address", + "name": "author name" + }, + "committer": { + "email": "email address", + "name": "committer name" + }, + "timestamp": "timestamp", + "message": "commit message", + "tree": "tree ID (sha-1 hash)", + "parents": [ list of parent IDs (string, sha-1 hash) ], + "signature": { + "signature": "base64 encoded PGP signature", + "data": "base64 encoded signed payload" + } or null +} +``` + +### Tree resource + +```json +{ + "id": "sha-1 hash", + "short_id": "truncated hash", + "entries": [ + { + "name": "entry name", + "id": "sha-1 hash", + "type": "tree" | "blob", + "mode": unix file mode + } + ] +} +``` + +### Reference resource + +```json +{ + "name": "name of reference (e.g. refs/heads/master)", + "target": "reference target (sha-1 hash)" +} +``` + +### Repository resource + +```json +{ + "id": integer, + "created": "timestamp", + "subject": "message subject", + "name": "repository name", + "description": "repository description (markdown)", + "visibility": "public" | "unlisted" | "private" +} +``` + +## Endpoints + +**Note**: usernames are prefixed with `~`. + +### GET /api/user/:username + +Retrieves a user resource. + +### GET /api/user + +Equivalent to [/api/user/:username](#GET-apiuserusername), implies the authenticated +user. + +### GET /api/:username/repos + +List of [repository resources](#repository-resource) owned by this user. + +**OAuth scope**: `info:read` + +### GET /api/repos + +Equivalent to [/api/:username/repos](#GET-apiusernamerepos), implies the +authenticated user. + +### POST /api/repos + +Creates a new [repository resource](#repository-resource). + +**OAuth scope**: `info:write` + +**Request body** + +```json +{ + "name": "repository name", + "description": "repository description (markdown)" (optional) + "visibility": "public" | "unlisted" | "private" (optional: default public) +} +``` + +**Response** + +The new [repository resource](#repository-resource) + +### GET /api/:username/repos/:name + +Retrieves a [repository resource](#repository-resource). + +**OAuth scope**: `info:read` + +### GET /api/repos/:name + +Equivalent to [/api/:username/repos/:name](#GET-apiusernamereposname), implies +the authenticated user. + +### PUT /api/repos/:name + +Updates a [repository resource](#repository-resource). + +**OAuth scope**: `info:write` + +**Request body** + +```json +{ + "name": "repository name" (optional), + "description": "repository description (markdown)" (optional), + "visibility": "public" | "unlisted" | "private" (optional) +} +``` + +**Notes** + +- Updating the name will create a redirect. + +### DELETE /api/repos/:name + +Deletes a [repository resource](#repository-resource). + +**OAuth scope**: `info:write` + +## Common data endpoints + +Endpoints for fetching git data from repos. + +### GET /api/:username/repos/:name/refs + +List of [reference resources](#reference-resource) in this git repository. + +**OAuth scope**: `data:read` + +### GET /api/repos/:name/refs + +Equivalent to [/api/:username/repos/refs](#GET-apiusernamereposnamerefs), +implies the authenticated user. + +### GET /api/:username/repos/:name/log + +List of the latest [commit resources](#commit-resource) on the default branch. + +**OAuth scope**: `data:read` + +### GET /api/repos/:name/log + +Equivalent to [/api/:username/repos/:name/log](#GET-apiusernamereposnamelog), +implies the authenticated user. + +### GET /api/:username/repos/:name/log/:ref + +List of the latest [commit resources](#commit-resource) starting from the given +reference (sha-1 ID or name). + +**OAuth scope**: `data:read` + +### GET /api/repos/:name/log/:ref + +Equivalent to [/api/:username/repos/:name/log/:ref](#GET-apiusernamereposnamelogref), +implies the authenticated user. + +## High-level data endpoints + +The endpoints work with paths instead of object IDs. + +### GET /api/:username/repos/:name/tree + +Returns the [tree resource](#tree-resource) for the latest commit to the default +branch. + +**OAuth scope**: `data:read` + +### GET /api/repos/:name/tree + +Equivalent to [/api/:username/repos/:name/tree](#GET-apiusernamereposnametree), +implies the authenticated user. + +### GET /api/:username/repos/:name/tree/:ref + +Returns the [tree resource](#tree-resource) for the given reference. + +**OAuth scope**: `data:read` + +### GET /api/repos/:name/tree/:ref + +Equivalent to [/api/:username/repos/:name/tree/:ref](#GET-apiusernamereposnametreeref), +implies the authenticated user. + +### GET /api/:username/repos/:name/tree/:ref/:path + +Returns the [tree resource](#tree-resource) for the given reference, following +the parent trees until the requested tree is found. In other words, this lists +the contents of a subdirectory by path. + +**OAuth scope**: `data:read` + +### GET /api/repos/:name/tree/:ref/:path + +Equivalent to [/api/:username/repos/:name/tree/:ref/:path](#GET-apiusernamereposnametreerefpath), +implies the authenticated user. + +### GET /api/:username/repos/:name/blob/:ref/:path + +Returns the blob at the given path of the tree specified by the given reference. + +**Response** + +The contents of the requested blob, as text/plain or as application/octet-stream +for binary blobs. + +**OAuth scope**: `data:read` + +### GET /api/repos/:name/blob/:ref/:path + +Equivalent to [/api/:username/repos/:name/blob/:ref/:path](#GET-apiusernamereposnameblobrefpath), +implies the authenticated user. + +## Low-level data endpoints + +These endpoints work with object IDs instead of paths. + +### GET /api/:username/repos/:name/tree/:id + +Returns the [tree resource](#tree-resource) with the given ID. + +**OAuth scope**: `data:read` + +### GET /api/repos/:name/tree/:id + +Equivalent to [/api/:username/repos/:name/tree/:id](#GET-apiusernamereposnametreeid), +implies the authenticated user. + +### GET /api/:username/repos/:name/blob/:id + +Returns the blob with the given ID. + +**Response** + +The contents of the requested blob, as text/plain or as application/octet-stream +for binary blobs. + +**OAuth scope**: `data:read` + +### GET /api/repos/:name/blob/:id + +Equivalent to [/api/:username/repos/:name/blob/:id](#GET-apiusernamereposnameblobid), +implies the authenticated user. diff --git a/git.sr.ht/index.md b/git.sr.ht/index.md index a6ec18e..a3407d0 100644 --- a/git.sr.ht/index.md +++ b/git.sr.ht/index.md @@ -7,6 +7,7 @@ sr.ht. **See also**: +- [API reference](api.md) - [Installation guide](installation.md) **Important**: git.sr.ht is a work in progress. As a consequence, URLs of @@ -93,6 +93,8 @@ dt { </dt> <dd> <a href="/git.sr.ht">User Manual</a> + — + <a href="/git.sr.ht/api.md">API Reference</a> </dd> </div> <div class="col-md-6"> |