From c38f0e9c95416022a28a22e63454cca316ddc81f Mon Sep 17 00:00:00 2001 From: Evan Read Date: Mon, 3 Sep 2018 12:12:28 +1000 Subject: More specificity and clarity for iid field in API documentation. --- doc/api/README.md | 25 +++++++++---------------- doc/api/milestones.md | 2 +- 2 files changed, 10 insertions(+), 17 deletions(-) diff --git a/doc/api/README.md b/doc/api/README.md index e2a6e87a2c3..e0f18a41f95 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -445,28 +445,21 @@ curl --request POST --header "PRIVATE-TOKEN: ********************" \ ## `id` vs `iid` -When you work with the API, you may notice two similar fields in API entities: -`id` and `iid`. The main difference between them is scope. + Some resources have two similarly-named fields. For example, [issues](issues.md), [merge requests](merge_requests.md), and [project milestones](milestones.md). The fields are: -For example, an issue might have `id: 46` and `iid: 5`. +- `id`. ID that is unique across all projects. +- `iid`. Additional, internal ID that is unique in the scope of a single project. -| Parameter | Description | -| --------- | ----------- | -| `id` | Is unique across all issues and is used for any API call | -| `iid` | Is unique only in scope of a single project. When you browse issues or merge requests with the Web UI, you see the `iid` | +> The `iid` is displayed in the web UI. -That means that if you want to get an issue via the API you should use the `id`: +If a resource has the `iid` field, it is often used instead of `id` to fetch the resource. -``` -GET /projects/42/issues/:id -``` +For example, suppose a project with `id: 42` has an issue with `id: 46` and `iid: 5`. In this case: -On the other hand, if you want to create a link to a web page you should use -the `iid`: +- A valid API call to retrieve the issue is `GET /projects/42/issues/5` +- An invalid API call to retrieve the issue is `GET /projects/42/issues/46`. -``` -GET /projects/42/issues/:iid -``` +> Not all resources with the `iid` field are fetched by `iid`. ## Data validation and error reporting diff --git a/doc/api/milestones.md b/doc/api/milestones.md index 07e66f89443..8f1a5c8e19b 100644 --- a/doc/api/milestones.md +++ b/doc/api/milestones.md @@ -19,7 +19,7 @@ Parameters: | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `iids[]` | Array[integer] | optional | Return only the milestones having the given `iid` | -| `state` | string | optional | Return only `active` or `closed` milestones` | +| `state` | string | optional | Return only `active` or `closed` milestones | | `search` | string | optional | Return only milestones with a title or description matching the provided string | ```bash -- cgit v1.2.1 From 2a8f094105a3b2dbf166043e170f10fcda259f33 Mon Sep 17 00:00:00 2001 From: Evan Read Date: Wed, 5 Sep 2018 10:38:03 +1000 Subject: Fix content to align with style guide. --- doc/api/README.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/doc/api/README.md b/doc/api/README.md index e0f18a41f95..ef4bb3fbd29 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -219,7 +219,8 @@ Impersonation tokens are used exactly like regular personal access tokens, and c ### Sudo -> Needs admin permissions. +NOTE: **Note:** +Needs admin permissions. All API requests support performing an API call as if you were another user, provided you are authenticated as an administrator with an OAuth or Personal Access Token that has the `sudo` scope. @@ -447,10 +448,11 @@ curl --request POST --header "PRIVATE-TOKEN: ********************" \ Some resources have two similarly-named fields. For example, [issues](issues.md), [merge requests](merge_requests.md), and [project milestones](milestones.md). The fields are: -- `id`. ID that is unique across all projects. -- `iid`. Additional, internal ID that is unique in the scope of a single project. +- `id`: ID that is unique across all projects. +- `iid`: additional, internal ID that is unique in the scope of a single project. -> The `iid` is displayed in the web UI. +NOTE: **Note:** +The `iid` is displayed in the web UI. If a resource has the `iid` field, it is often used instead of `id` to fetch the resource. @@ -459,7 +461,8 @@ For example, suppose a project with `id: 42` has an issue with `id: 46` and `iid - A valid API call to retrieve the issue is `GET /projects/42/issues/5` - An invalid API call to retrieve the issue is `GET /projects/42/issues/46`. -> Not all resources with the `iid` field are fetched by `iid`. +NOTE: **Note:** +Not all resources with the `iid` field are fetched by `iid`. ## Data validation and error reporting -- cgit v1.2.1 From 3adf563a8914f0f676bccd6bec14a7449b36dac1 Mon Sep 17 00:00:00 2001 From: Evan Read Date: Thu, 6 Sep 2018 09:00:05 +1000 Subject: More clarification. Replace inline hyperlinks with reference style. --- doc/api/README.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/doc/api/README.md b/doc/api/README.md index ef4bb3fbd29..5cb883a83e5 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -220,7 +220,7 @@ Impersonation tokens are used exactly like regular personal access tokens, and c ### Sudo NOTE: **Note:** -Needs admin permissions. +Only available to [administrators][permissions]. All API requests support performing an API call as if you were another user, provided you are authenticated as an administrator with an OAuth or Personal Access Token that has the `sudo` scope. @@ -446,7 +446,7 @@ curl --request POST --header "PRIVATE-TOKEN: ********************" \ ## `id` vs `iid` - Some resources have two similarly-named fields. For example, [issues](issues.md), [merge requests](merge_requests.md), and [project milestones](milestones.md). The fields are: + Some resources have two similarly-named fields. For example, [issues], [merge requests], and [project milestones]. The fields are: - `id`: ID that is unique across all projects. - `iid`: additional, internal ID that is unique in the scope of a single project. @@ -454,7 +454,7 @@ curl --request POST --header "PRIVATE-TOKEN: ********************" \ NOTE: **Note:** The `iid` is displayed in the web UI. -If a resource has the `iid` field, it is often used instead of `id` to fetch the resource. +If a resource has the `iid` field and the `id` field, the `iid` field is usually used instead of `id` to fetch the resource. For example, suppose a project with `id: 42` has an issue with `id: 46` and `iid: 5`. In this case: @@ -462,7 +462,7 @@ For example, suppose a project with `id: 42` has an issue with `id: 46` and `iid - An invalid API call to retrieve the issue is `GET /projects/42/issues/46`. NOTE: **Note:** -Not all resources with the `iid` field are fetched by `iid`. +Not all resources with the `iid` field are fetched by `iid`. For guidance on which field to use, see the documentation for the specific resource. ## Data validation and error reporting @@ -562,3 +562,7 @@ programming languages. Visit the [GitLab website] for a complete list. [ce-5951]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5951 [ce-9099]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9099 [pat]: ../user/profile/personal_access_tokens.md +[issues]: issues.md +[merge requests]: merge_requests.md +[project milestones]: milestones.md +[permissions]: ../user/permissions.md -- cgit v1.2.1 From ac2adcf77f94a8e77c1e78694e230bc6b82f90d6 Mon Sep 17 00:00:00 2001 From: Evan Read Date: Fri, 7 Sep 2018 08:41:52 +1000 Subject: Inline rather than reference links. --- doc/api/README.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/doc/api/README.md b/doc/api/README.md index 5cb883a83e5..44c5815bc4c 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -220,7 +220,7 @@ Impersonation tokens are used exactly like regular personal access tokens, and c ### Sudo NOTE: **Note:** -Only available to [administrators][permissions]. +Only available to [administrators](../user/permissions.md). All API requests support performing an API call as if you were another user, provided you are authenticated as an administrator with an OAuth or Personal Access Token that has the `sudo` scope. @@ -446,7 +446,7 @@ curl --request POST --header "PRIVATE-TOKEN: ********************" \ ## `id` vs `iid` - Some resources have two similarly-named fields. For example, [issues], [merge requests], and [project milestones]. The fields are: + Some resources have two similarly-named fields. For example, [issues](issues.md), [merge requests](merge_requests.md), and [project milestones](merge_requests.md). The fields are: - `id`: ID that is unique across all projects. - `iid`: additional, internal ID that is unique in the scope of a single project. @@ -562,7 +562,3 @@ programming languages. Visit the [GitLab website] for a complete list. [ce-5951]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5951 [ce-9099]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9099 [pat]: ../user/profile/personal_access_tokens.md -[issues]: issues.md -[merge requests]: merge_requests.md -[project milestones]: milestones.md -[permissions]: ../user/permissions.md -- cgit v1.2.1 From b985d2877363f9c87ddfb7e34edcc6a51c831972 Mon Sep 17 00:00:00 2001 From: Evan Read Date: Tue, 11 Sep 2018 09:02:52 +1000 Subject: Add prerequisite knowledge blurb and minor style fixes. --- doc/api/README.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/doc/api/README.md b/doc/api/README.md index 44c5815bc4c..8e3abb8ddce 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -3,6 +3,8 @@ Automate GitLab via a simple and powerful API. All definitions can be found under [`/lib/api`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/api). +The main GitLab API is a [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) API. Therefore, documentation in this section assumes knowledge of REST concepts. + ## Resources Documentation for various API resources can be found separately in the @@ -77,8 +79,8 @@ Going forward, we will start on moving to controller-specific endpoints. GraphQL has a number of benefits: 1. We avoid having to maintain two different APIs. -2. Callers of the API can request only what they need. -3. It is versioned by default. +1. Callers of the API can request only what they need. +1. It is versioned by default. It will co-exist with the current v4 REST API. If we have a v5 API, this should be a compatibility layer on top of GraphQL. @@ -139,8 +141,9 @@ There are three ways to authenticate with the GitLab API: 1. [Session cookie](#session-cookie) For admins who want to authenticate with the API as a specific user, or who want to build applications or scripts that do so, two options are available: + 1. [Impersonation tokens](#impersonation-tokens) -2. [Sudo](#sudo) +1. [Sudo](#sudo) If authentication information is invalid or omitted, an error message will be returned with status code `401`: -- cgit v1.2.1