From aaf6be3ee6f6fb353571c35c68aa081dd043adc2 Mon Sep 17 00:00:00 2001 From: stevegt Date: Mon, 25 Jun 2018 05:12:46 -0700 Subject: [PATCH] Create api-usage doc page (#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 #4037, #3673, and #4243 * Close #4247 Signed-off-by: Steve Traugott --- docs/content/doc/advanced/api-usage.en-us.md | 75 ++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 docs/content/doc/advanced/api-usage.en-us.md diff --git a/docs/content/doc/advanced/api-usage.en-us.md b/docs/content/doc/advanced/api-usage.en-us.md new file mode 100644 index 0000000000..f04a99f14b --- /dev/null +++ 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":"..."}] +```