diff options
| author | Evan Read <eread@gitlab.com> | 2018-09-03 05:12:28 +0300 |
|---|---|---|
| committer | Evan Read <eread@gitlab.com> | 2018-09-04 03:52:39 +0300 |
| commit | c38f0e9c95416022a28a22e63454cca316ddc81f (patch) | |
| tree | fa448ee71d31683651d141c8fd056bc59246110d /doc/api | |
| parent | 658cd117293da37077ec67046cb1a72fde1ecc35 (diff) | |
More specificity and clarity for iid field in API documentation.
Diffstat (limited to 'doc/api')
| -rw-r--r-- | doc/api/README.md | 25 | ||||
| -rw-r--r-- | 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 |