From 7065a6124c1ed2cad1515904bfa60259df23a1bf Mon Sep 17 00:00:00 2001 From: Tony Lee Date: Tue, 19 Jun 2018 03:37:26 +0800 Subject: [PATCH 1/5] add api user guides in doc --- docs/content/doc/user-guides.en-us.md | 13 +++++++++++++ docs/content/doc/user-guides/api-authentication.md | 12 ++++++++++++ 2 files changed, 25 insertions(+) create mode 100644 docs/content/doc/user-guides.en-us.md create mode 100644 docs/content/doc/user-guides/api-authentication.md diff --git a/docs/content/doc/user-guides.en-us.md b/docs/content/doc/user-guides.en-us.md new file mode 100644 index 0000000000000..468289cbbab44 --- /dev/null +++ b/docs/content/doc/user-guides.en-us.md @@ -0,0 +1,13 @@ +--- +date: "2018-06-19T16:00:00+02:00" +title: "User-guides" +slug: "user-guides" +weight: 45 +toc: false +draft: false +menu: + sidebar: + name: "User-guides" + weight: 45 + identifier: "user-guides" +--- diff --git a/docs/content/doc/user-guides/api-authentication.md b/docs/content/doc/user-guides/api-authentication.md new file mode 100644 index 0000000000000..a28619bc3ec11 --- /dev/null +++ b/docs/content/doc/user-guides/api-authentication.md @@ -0,0 +1,12 @@ +# API user guide + +## User + +### /users/{username}/tokens + +Basic usage: + +``` +$ curl --request GET --url https://m:mypassword@git.your.host/api/v1/users/m/tokens +[{"name":"test","sha1":"..."},{"name":"dev","sha1":"..."}] +``` From 44171d16fb8c9ed3366f0fe4046f548617b34174 Mon Sep 17 00:00:00 2001 From: Tony Lee Date: Thu, 21 Jun 2018 01:58:14 +0800 Subject: [PATCH 2/5] update user-guides api page --- docs/content/doc/user-guides.en-us.md | 6 ++--- .../doc/user-guides/api-authentication.md | 24 +++++++++++++++---- 2 files changed, 23 insertions(+), 7 deletions(-) diff --git a/docs/content/doc/user-guides.en-us.md b/docs/content/doc/user-guides.en-us.md index 468289cbbab44..6139cbf81c9e8 100644 --- a/docs/content/doc/user-guides.en-us.md +++ b/docs/content/doc/user-guides.en-us.md @@ -1,13 +1,13 @@ --- date: "2018-06-19T16:00:00+02:00" -title: "User-guides" +title: "User Guides" slug: "user-guides" -weight: 45 +weight: 35 toc: false draft: false menu: sidebar: - name: "User-guides" + name: "User Guides" weight: 45 identifier: "user-guides" --- diff --git a/docs/content/doc/user-guides/api-authentication.md b/docs/content/doc/user-guides/api-authentication.md index a28619bc3ec11..e82aa0c98726d 100644 --- a/docs/content/doc/user-guides/api-authentication.md +++ b/docs/content/doc/user-guides/api-authentication.md @@ -1,12 +1,28 @@ -# API user guide +--- +date: "2018-06-19T16:00:00+02:00" +title: "User Guides: API Usage" +slug: "api-usage" +weight: 10 +toc: true +draft: false +menu: + sidebar: + parent: "user-guides" + name: "API Usage" + weight: 10 + identifier: "api-usage" +--- -## User +## API Usage ### /users/{username}/tokens -Basic usage: +Usage: +``` +$ curl --request GET --url https://m:yourpassword@git.your.host/api/v1/users/m/tokens +``` +Response: ``` -$ curl --request GET --url https://m:mypassword@git.your.host/api/v1/users/m/tokens [{"name":"test","sha1":"..."},{"name":"dev","sha1":"..."}] ``` From facdb860bcc7a785a695193cc6e4d09086569771 Mon Sep 17 00:00:00 2001 From: Tony Lee Date: Thu, 21 Jun 2018 17:47:57 +0800 Subject: [PATCH 3/5] fix typo: user guides -> user guide --- .../doc/{user-guides.en-us.md => user-guide.en-us.md} | 8 ++++---- docs/content/doc/user-guides/api-authentication.md | 4 ++-- 2 files changed, 6 insertions(+), 6 deletions(-) rename docs/content/doc/{user-guides.en-us.md => user-guide.en-us.md} (53%) diff --git a/docs/content/doc/user-guides.en-us.md b/docs/content/doc/user-guide.en-us.md similarity index 53% rename from docs/content/doc/user-guides.en-us.md rename to docs/content/doc/user-guide.en-us.md index 6139cbf81c9e8..9af7951776feb 100644 --- a/docs/content/doc/user-guides.en-us.md +++ b/docs/content/doc/user-guide.en-us.md @@ -1,13 +1,13 @@ --- date: "2018-06-19T16:00:00+02:00" -title: "User Guides" -slug: "user-guides" +title: "User Guide" +slug: "user-guide" weight: 35 toc: false draft: false menu: sidebar: - name: "User Guides" + name: "User Guide" weight: 45 - identifier: "user-guides" + identifier: "user-guide" --- diff --git a/docs/content/doc/user-guides/api-authentication.md b/docs/content/doc/user-guides/api-authentication.md index e82aa0c98726d..4483cc1f18f4f 100644 --- a/docs/content/doc/user-guides/api-authentication.md +++ b/docs/content/doc/user-guides/api-authentication.md @@ -1,13 +1,13 @@ --- date: "2018-06-19T16:00:00+02:00" -title: "User Guides: API Usage" +title: "User Guide: API Usage" slug: "api-usage" weight: 10 toc: true draft: false menu: sidebar: - parent: "user-guides" + parent: "user-guide" name: "API Usage" weight: 10 identifier: "api-usage" From 5b059686769bddaa11c570d599fb235e07bfa3ea Mon Sep 17 00:00:00 2001 From: Tony Lee Date: Fri, 22 Jun 2018 07:56:02 +0800 Subject: [PATCH 4/5] move api-usage page under advanced category --- .../{user-guides => advanced}/api-authentication.md | 8 ++++---- docs/content/doc/user-guide.en-us.md | 13 ------------- 2 files changed, 4 insertions(+), 17 deletions(-) rename docs/content/doc/{user-guides => advanced}/api-authentication.md (82%) delete mode 100644 docs/content/doc/user-guide.en-us.md diff --git a/docs/content/doc/user-guides/api-authentication.md b/docs/content/doc/advanced/api-authentication.md similarity index 82% rename from docs/content/doc/user-guides/api-authentication.md rename to docs/content/doc/advanced/api-authentication.md index 4483cc1f18f4f..e5bda7014be58 100644 --- a/docs/content/doc/user-guides/api-authentication.md +++ b/docs/content/doc/advanced/api-authentication.md @@ -1,15 +1,15 @@ --- date: "2018-06-19T16:00:00+02:00" -title: "User Guide: API Usage" +title: "API Usage" slug: "api-usage" -weight: 10 +weight: 40 toc: true draft: false menu: sidebar: - parent: "user-guide" + parent: "advanced" name: "API Usage" - weight: 10 + weight: 40 identifier: "api-usage" --- diff --git a/docs/content/doc/user-guide.en-us.md b/docs/content/doc/user-guide.en-us.md deleted file mode 100644 index 9af7951776feb..0000000000000 --- a/docs/content/doc/user-guide.en-us.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -date: "2018-06-19T16:00:00+02:00" -title: "User Guide" -slug: "user-guide" -weight: 35 -toc: false -draft: false -menu: - sidebar: - name: "User Guide" - weight: 45 - identifier: "user-guide" ---- From d4112d4670e9f9750f3ab75610a7a82635fb2378 Mon Sep 17 00:00:00 2001 From: Steve Traugott Date: Sun, 24 Jun 2018 14:51:02 -0700 Subject: [PATCH 5/5] 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 --- .../doc/advanced/api-authentication.md | 28 ------- docs/content/doc/advanced/api-usage.en-us.md | 75 +++++++++++++++++++ 2 files changed, 75 insertions(+), 28 deletions(-) delete mode 100644 docs/content/doc/advanced/api-authentication.md create mode 100644 docs/content/doc/advanced/api-usage.en-us.md diff --git a/docs/content/doc/advanced/api-authentication.md b/docs/content/doc/advanced/api-authentication.md deleted file mode 100644 index e5bda7014be58..0000000000000 --- a/docs/content/doc/advanced/api-authentication.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -date: "2018-06-19T16: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" ---- - -## API Usage - -### /users/{username}/tokens - -Usage: -``` -$ curl --request GET --url https://m:yourpassword@git.your.host/api/v1/users/m/tokens -``` - -Response: -``` -[{"name":"test","sha1":"..."},{"name":"dev","sha1":"..."}] -``` 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 0000000000000..f04a99f14b123 --- /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":"..."}] +```