|
| 1 | +# Overview |
| 2 | + |
| 3 | +This is a set of documents which describes Gogs REST API v1 usage, since it's still in early stage: |
| 4 | + |
| 5 | +1. Content of documentation and APIs are subject to change. |
| 6 | +2. We do not provide documentation in other languages. |
| 7 | +3. Aim to be in the format that is similar to [GitHub REST API v3](https://developer.github.com/v3/). |
| 8 | + |
| 9 | +If you have any questions or concern, please [file an issue](https://github.com/gogits/go-gogs-client/issues/new). :blush: |
| 10 | + |
| 11 | +## Installation |
| 12 | + |
| 13 | +The API is preinstalled with the base Gogs deployment. See [current version](#current-version) and [API source code](https://github.com/gogs/gogs/tree/master/routes/api) for more details. |
| 14 | + |
| 15 | +## Current Version |
| 16 | + |
| 17 | +All Gogs APIs are under **v1** using request path prefix `/api/v1`. |
| 18 | + |
| 19 | +## Schema |
| 20 | + |
| 21 | +All data is sent and received as JSON. |
| 22 | + |
| 23 | +``` |
| 24 | +HTTP/2 200 |
| 25 | +content-type: application/json; charset=UTF-8 |
| 26 | +date: 2018年12月15日 01:55:28 GMT |
| 27 | +server: Caddy |
| 28 | +content-length: 175 |
| 29 | +``` |
| 30 | + |
| 31 | +All timestamps return in ISO 8601 format: |
| 32 | + |
| 33 | +``` |
| 34 | +YYYY-MM-DDTHH:MM:SSZ |
| 35 | +``` |
| 36 | + |
| 37 | +## Authentication |
| 38 | + |
| 39 | +There are three ways to authenticate through Gogs API v1. Requests that require authentication will return `404 Not Found`, instead of `403 Forbidden`, in some places. This is to prevent the accidental leakage of private repositories to unauthorized users. |
| 40 | + |
| 41 | +## Basic Authentication |
| 42 | + |
| 43 | +``` |
| 44 | +curl -u "unknwon" https://try.gogs.io/api/v1/users/unknwon/tokens |
| 45 | +``` |
| 46 | + |
| 47 | +Basic authentication can only be used to obtain access tokens. |
| 48 | + |
| 49 | +### Access Token |
| 50 | + |
| 51 | +Personal access tokens are easier to manage and use, but except for few APIs (i.e. generate or get a access token), and they can be sent in **header** or **URL query**. |
| 52 | + |
| 53 | +``` |
| 54 | +$ curl -H "Authorization: token {ACCESS_TOKEN}" https://try.gogs.io/api/v1/user/repos |
| 55 | +$ curl https://try.gogs.io/api/v1/user/repos?token={ACCESS_TOKEN} |
| 56 | +``` |
| 57 | + |
| 58 | +## Parameters |
| 59 | + |
| 60 | +Parameters of all requests use POST method can be passed through a normal HTML form or JSON data, but sending JSON is recommended. |
| 61 | + |
| 62 | +## Clients |
| 63 | + |
| 64 | +- [Go](https://github.com/gogs/go-gogs-client) |
| 65 | +- [Android](https://github.com/unfoldingWord-dev/android-gogs-client) |
| 66 | + |
| 67 | +## Notes |
| 68 | + |
| 69 | +- The style of documentation is heavily influenced by [GitHub Developer](https://developer.github.com/). |
0 commit comments