forked from mulesoft/api-console
-
Notifications
You must be signed in to change notification settings - Fork 0
/
apiary.apib
187 lines (145 loc) · 5.43 KB
/
apiary.apib
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
FORMAT: 1A
HOST: http://polls.apiblueprint.org/
# Table 2.5
Polls is a simple API allowing consumers to view polls and vote in them.
# API Root [/]
This resource does not have any attributes. Instead it offers the initial
API affordances in the form of the links in the JSON body.
It is recommend to follow the “url” link values,
[Link](https://tools.ietf.org/html/rfc5988) or Location headers where
applicable to retrieve resources. Instead of constructing your own URLs,
to keep your client decoupled from implementation details.
## Group Items
Resources related to items in the API.
## Items [/items]
## Item [/items/{item_id}]
## Related Author [/items/{item_id}/relationships/author]
## Related Attributed Author [/items/{item_id}/relationships/attributed-author]
## Related Items [/items/{item_id}/relationships/items]
## Related Locations [/items/{item_id}/relationships/locations]
## Related Comments [/items/{item_id}/relationships/comments]
## Related Category [/items/{item_id}/relationships/category]
## Related Tags [/items/{item_id}/relationships/tags]
## Group Questions
Resources related to questions in the API.
## Question [/questions/{question_id}]
A Question object has the following attributes:
+ question
+ published_at - An ISO8601 date when the question was published.
+ url
+ choices - An array of Choice objects.
+ Parameters
+ question_id: 1 (required, number) - ID of the Question in form of an integer
### View a Questions Detail [GET]
+ Response 200 (application/json)
{
"question": "Favourite programming language?",
"published_at": "2014-11-11T08:40:51.620Z",
"url": "/questions/1",
"choices": [
{
"choice": "Swift",
"url": "/questions/1/choices/1",
"votes": 2048
}, {
"choice": "Python",
"url": "/questions/1/choices/2",
"votes": 1024
}, {
"choice": "Objective-C",
"url": "/questions/1/choices/3",
"votes": 512
}, {
"choice": "Ruby",
"url": "/questions/1/choices/4",
"votes": 256
}
]
}
## Choice [/questions/{question_id}/choices/{choice_id}]
+ Parameters
+ question_id: 1 (required, number) - ID of the Question in form of an integer
+ choice_id: 1 (required, number) - ID of the Choice in form of an integer
### Vote on a Choice [POST]
This action allows you to vote on a question's choice.
+ Response 201
+ Headers
Location: /questions/1
## Questions Collection [/questions{?page}]
+ Parameters
+ page: 1 (optional, number) - The page of questions to return
### List All Questions [GET]
+ Response 200 (application/json)
+ Headers
Link: </questions?page=2>; rel="next"
+ Body
[
{
"question": "Favourite programming language?",
"published_at": "2014-11-11T08:40:51.620Z",
"url": "/questions/1",
"choices": [
{
"choice": "Swift",
"url": "/questions/1/choices/1",
"votes": 2048
}, {
"choice": "Python",
"url": "/questions/1/choices/2",
"votes": 1024
}, {
"choice": "Objective-C",
"url": "/questions/1/choices/3",
"votes": 512
}, {
"choice": "Ruby",
"url": "/questions/1/choices/4",
"votes": 256
}
]
}
]
### Create a New Question [POST]
You may create your own question using this action. It takes a JSON
object containing a question and a collection of answers in the
form of choices.
+ question (string) - The question
+ choices (array[string]) - A collection of choices.
+ Request (application/json)
{
"question": "Favourite programming language?",
"choices": [
"Swift",
"Python",
"Objective-C",
"Ruby"
]
}
+ Response 201 (application/json)
+ Headers
Location: /questions/2
+ Body
{
"question": "Favourite programming language?",
"published_at": "2014-11-11T08:40:51.620Z",
"url": "/questions/2",
"choices": [
{
"choice": "Swift",
"url": "/questions/2/choices/1",
"votes": 0
}, {
"choice": "Python",
"url": "/questions/2/choices/2",
"votes": 0
}, {
"choice": "Objective-C",
"url": "/questions/2/choices/3",
"votes": 0
}, {
"choice": "Ruby",
"url": "/questions/2/choices/4",
"votes": 0
}
]
}