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,13 +96,30 @@ curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" --header "SUDO: username" "h
96 curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" --header "SUDO: 23" "http://example.com/api/v3/projects" 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 When listing resources you can pass the following parameters: 101 When listing resources you can pass the following parameters:
102 102
103 + `page` (default: `1`) - page number 103 + `page` (default: `1`) - page number
104 + `per_page` (default: `20`, max: `100`) - number of items to list per page 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 ## Contents 123 ## Contents
107 124
108 + [Users](users.md) 125 + [Users](users.md)
doc/api/issues.md
@@ -11,6 +11,7 @@ GET /issues @@ -11,6 +11,7 @@ GET /issues
11 [ 11 [
12 { 12 {
13 "id": 43, 13 "id": 43,
  14 + "iid": 3,
14 "project_id": 8, 15 "project_id": 8,
15 "title": "4xx/5xx pages", 16 "title": "4xx/5xx pages",
16 "description": "", 17 "description": "",
@@ -31,6 +32,7 @@ GET /issues @@ -31,6 +32,7 @@ GET /issues
31 }, 32 },
32 { 33 {
33 "id": 42, 34 "id": 42,
  35 + "iid": 4,
34 "project_id": 8, 36 "project_id": 8,
35 "title": "Add user settings", 37 "title": "Add user settings",
36 "description": "", 38 "description": "",
@@ -100,6 +102,7 @@ Parameters: @@ -100,6 +102,7 @@ Parameters:
100 ```json 102 ```json
101 { 103 {
102 "id": 42, 104 "id": 42,
  105 + "iid": 3,
103 "project_id": 8, 106 "project_id": 8,
104 "title": "Add user settings", 107 "title": "Add user settings",
105 "description": "", 108 "description": "",
doc/api/merge_requests.md
@@ -15,6 +15,7 @@ Parameters: @@ -15,6 +15,7 @@ Parameters:
15 [ 15 [
16 { 16 {
17 "id":1, 17 "id":1,
  18 + "iid":1,
18 "target_branch":"master", 19 "target_branch":"master",
19 "source_branch":"test1", 20 "source_branch":"test1",
20 "project_id":3, 21 "project_id":3,
@@ -59,6 +60,7 @@ Parameters: @@ -59,6 +60,7 @@ Parameters:
59 ```json 60 ```json
60 { 61 {
61 "id":1, 62 "id":1,
  63 + "iid":1,
62 "target_branch":"master", 64 "target_branch":"master",
63 "source_branch":"test1", 65 "source_branch":"test1",
64 "project_id":3, 66 "project_id":3,
doc/api/milestones.md
@@ -10,6 +10,7 @@ GET /projects/:id/milestones @@ -10,6 +10,7 @@ GET /projects/:id/milestones
10 [ 10 [
11 { 11 {
12 "id":12, 12 "id":12,
  13 + "iid":3,
13 "project_id":16, 14 "project_id":16,
14 "title":"10.0", 15 "title":"10.0",
15 "description":"Version", 16 "description":"Version",