Create api-usage doc page (gogs#4306)

* add api user guides in doc * update user-guides api page * fix typo: user guides -> user guide * move api-usage page under advanced category * flesh out API usage docs * Build on work by @tungsheng * Address issues raised in gogs#4037, gogs#3673, and gogs#4243 * Close gogs#4247 Signed-off-by: Steve Traugott <stevegt@t7a.org>
Martchus · Jun 25, 2018 · aaf6be3 · aaf6be3
1 parent 8bb9b67
commit aaf6be3
Showing 1 changed file with 75 additions and 0 deletions.
diff --git a/docs/content/doc/advanced/api-usage.en-us.md b/docs/content/doc/advanced/api-usage.en-us.md
@@ -0,0 +1,75 @@
+---
+date: "2018-06-24:00:00+02:00"
+title: "API Usage"
+slug: "api-usage"
+weight: 40
+toc: true
+draft: false
+menu:
+  sidebar:
+    parent: "advanced"
+    name: "API Usage"
+    weight: 40
+    identifier: "api-usage"
+---
+
+# Gitea API Usage
+
+## Enabling/configuring API access
+
+By default, `ENABLE_SWAGGER_ENDPOINT` is true, and
+`MAX_RESPONSE_ITEMS` is set to 50.  See [Config Cheat
+Sheet](https://docs.gitea.io/en-us/config-cheat-sheet/) for more
+information.
+
+## Authentication via the API
+
+Gitea supports these methods of API authentication:
+
+- HTTP basic authentication
+- `token=...` parameter in URL query string
+- `access_token=...` parameter in URL query string
+- `Authorization: token ...` header in HTTP headers
+
+All of these methods accept the same apiKey token type.  You can
+better understand this by looking at the code -- as of this writing,
+Gitea parses queries and headers to find the token in
+[modules/auth/auth.go](https://github.com/go-gitea/gitea/blob/6efdcaed86565c91a3dc77631372a9cc45a58e89/modules/auth/auth.go#L47).
+
+You can create an apiKey token via your gitea install's web interface:
+`Settings | Applications | Generate New Token`.
+
+### More on the `Authorization:` header
+
+For historical reasons, Gitea needs the word `token` included before
+the apiKey token in an authorization header, like this:
+
+```
+Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675
+```
+
+In a `curl` command, for instance, this would look like:
+
+```
+curl -X POST "http://localhost:4000/api/v1/repos/test1/test1/issues" \
+    -H "accept: application/json" \
+    -H "Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675" \
+    -H "Content-Type: application/json" -d "{ \"body\": \"testing\", \"title\": \"test 20\"}" -i
+```
+
+As mentioned above, the token used is the same one you would use in
+the `token=` string in a GET request.
+
+## Listing your issued tokens via the API
+
+As mentioned in
+[#3842](https://github.com/go-gitea/gitea/issues/3842#issuecomment-397743346),
+`/users/:name/tokens` is special and requires you to authenticate
+using BasicAuth, as follows:
+
+### Using basic authentication:
+
+```
+$ curl --request GET --url https://yourusername:yourpassword@gitea.your.host/api/v1/users/yourusername/tokens
+[{"name":"test","sha1":"..."},{"name":"dev","sha1":"..."}]
+```