Commit 02693b72a4240a9d94246e590775a66eb48c55ed

Authored by Dmitriy Zaporozhets
1 parent 12800e54

Explain iid in API

doc/api/README.md
... ... @@ -96,13 +96,30 @@ curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" --header "SUDO: username" "h
96 96 curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" --header "SUDO: 23" "http://example.com/api/v3/projects"
97 97 ```
98 98  
99   -#### Pagination
  99 +## Pagination
100 100  
101 101 When listing resources you can pass the following parameters:
102 102  
103 103 + `page` (default: `1`) - page number
104 104 + `per_page` (default: `20`, max: `100`) - number of items to list per page
105 105  
  106 +## id vs iid
  107 +
  108 +When you work with API you may notice two similar fields in api entites: id and iid.
  109 +The main difference between them is scope. Example:
  110 +
  111 +Issue
  112 + id: 46
  113 + iid: 5
  114 +
  115 +* id - is uniq across all Issues table. It used for any api calls.
  116 +* iid - is uniq only in scope of single project. When you browse issues or merge requests with Web UI - you see iid.
  117 +
  118 +So if you want to get issue with api you use `http://host/api/v3/.../issues/:id.json`
  119 +But when you want to create a link to web page - use `http:://host/project/issues/:iid.json`
  120 +
  121 +
  122 +
106 123 ## Contents
107 124  
108 125 + [Users](users.md)
... ...
doc/api/issues.md
... ... @@ -11,6 +11,7 @@ GET /issues
11 11 [
12 12 {
13 13 "id": 43,
  14 + "iid": 3,
14 15 "project_id": 8,
15 16 "title": "4xx/5xx pages",
16 17 "description": "",
... ... @@ -31,6 +32,7 @@ GET /issues
31 32 },
32 33 {
33 34 "id": 42,
  35 + "iid": 4,
34 36 "project_id": 8,
35 37 "title": "Add user settings",
36 38 "description": "",
... ... @@ -100,6 +102,7 @@ Parameters:
100 102 ```json
101 103 {
102 104 "id": 42,
  105 + "iid": 3,
103 106 "project_id": 8,
104 107 "title": "Add user settings",
105 108 "description": "",
... ...
doc/api/merge_requests.md
... ... @@ -15,6 +15,7 @@ Parameters:
15 15 [
16 16 {
17 17 "id":1,
  18 + "iid":1,
18 19 "target_branch":"master",
19 20 "source_branch":"test1",
20 21 "project_id":3,
... ... @@ -59,6 +60,7 @@ Parameters:
59 60 ```json
60 61 {
61 62 "id":1,
  63 + "iid":1,
62 64 "target_branch":"master",
63 65 "source_branch":"test1",
64 66 "project_id":3,
... ...
doc/api/milestones.md
... ... @@ -10,6 +10,7 @@ GET /projects/:id/milestones
10 10 [
11 11 {
12 12 "id":12,
  13 + "iid":3,
13 14 "project_id":16,
14 15 "title":"10.0",
15 16 "description":"Version",
... ...