Commit 3fd0a469 authored by Marcia Ramos's avatar Marcia Ramos

Merge branch 'fix-id-vs-iid' into 'master'

More specificity and clarity for iid field in API documentation.

Closes gitlab-ee#7019

See merge request gitlab-org/gitlab-ce!21490
parents aa1e9a2d b985d287
...@@ -3,6 +3,8 @@ ...@@ -3,6 +3,8 @@
Automate GitLab via a simple and powerful API. All definitions can be found 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). 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 ## Resources
Documentation for various API resources can be found separately in the Documentation for various API resources can be found separately in the
...@@ -78,8 +80,8 @@ Going forward, we will start on moving to ...@@ -78,8 +80,8 @@ Going forward, we will start on moving to
controller-specific endpoints. GraphQL has a number of benefits: controller-specific endpoints. GraphQL has a number of benefits:
1. We avoid having to maintain two different APIs. 1. We avoid having to maintain two different APIs.
2. Callers of the API can request only what they need. 1. Callers of the API can request only what they need.
3. It is versioned by default. 1. It is versioned by default.
It will co-exist with the current v4 REST API. If we have a v5 API, this should 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. be a compatibility layer on top of GraphQL.
...@@ -140,8 +142,9 @@ There are three ways to authenticate with the GitLab API: ...@@ -140,8 +142,9 @@ There are three ways to authenticate with the GitLab API:
1. [Session cookie](#session-cookie) 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: 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) 1. [Impersonation tokens](#impersonation-tokens)
2. [Sudo](#sudo) 1. [Sudo](#sudo)
If authentication information is invalid or omitted, an error message will be If authentication information is invalid or omitted, an error message will be
returned with status code `401`: returned with status code `401`:
...@@ -220,7 +223,8 @@ Impersonation tokens are used exactly like regular personal access tokens, and c ...@@ -220,7 +223,8 @@ Impersonation tokens are used exactly like regular personal access tokens, and c
### Sudo ### Sudo
> Needs admin permissions. NOTE: **Note:**
Only available to [administrators](../user/permissions.md).
All API requests support performing an API call as if you were another user, 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. provided you are authenticated as an administrator with an OAuth or Personal Access Token that has the `sudo` scope.
...@@ -446,28 +450,23 @@ curl --request POST --header "PRIVATE-TOKEN: ********************" \ ...@@ -446,28 +450,23 @@ curl --request POST --header "PRIVATE-TOKEN: ********************" \
## `id` vs `iid` ## `id` vs `iid`
When you work with the API, you may notice two similar fields in API entities: 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` and `iid`. The main difference between them is scope.
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 | NOTE: **Note:**
| --------- | ----------- | The `iid` is displayed in the web UI.
| `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` |
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 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:
GET /projects/42/issues/:id
```
On the other hand, if you want to create a link to a web page you should use - A valid API call to retrieve the issue is `GET /projects/42/issues/5`
the `iid`: - An invalid API call to retrieve the issue is `GET /projects/42/issues/46`.
``` NOTE: **Note:**
GET /projects/42/issues/: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 ## Data validation and error reporting
......
...@@ -19,7 +19,7 @@ Parameters: ...@@ -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 | | `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` | | `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 | | `search` | string | optional | Return only milestones with a title or description matching the provided string |
```bash ```bash
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment