Commit c38f0e9c authored by Evan Read's avatar Evan Read

More specificity and clarity for iid field in API documentation.

parent 658cd117
...@@ -445,28 +445,21 @@ curl --request POST --header "PRIVATE-TOKEN: ********************" \ ...@@ -445,28 +445,21 @@ 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](milestones.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 | > 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, it is often 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`.
``` > Not all resources with the `iid` field are fetched by `iid`.
GET /projects/42/issues/:iid
```
## 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