-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathapiary.apib
196 lines (145 loc) · 5.24 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
188
189
190
191
192
193
194
195
196
FORMAT: 1A
# Spatial Tracker APIs
For now we go with HTTP Basic Auth,
so all calls asume Authentication header is present
For further versions either:
- HMAC http://restcookbook.com/Basics/loggingin/
- SSL
- OAuth
# Group Users
## New User [/user]
Create a new account for the user
### Register New [POST]
+ Request (application/json)
+Attributes (object)
+ login: `dragon` (string, required)
+ email: `[email protected]` (string, required)
+ password: `sEcrEt123` (string, required)
+ Response 201
User account was created
+ Headers
Location: `base/uri/to/tracker/user/new_user`
+ Response 400 (application/json)
+ Attributes (object)
+ errors (array)
+ `name taken` (string)
+ `invalid email` (string)
+ `missing password` (string)
## Some User [/user/{login}]
Anyone can view details of any user.
To edit or delete user credentials for that user must
be supplied instead of just login.
+ Parameters
+ login: `pepa.zdepa` (string) Users login processed to be URL friendly
### Show Details [GET]
+ Response 200 (application/json)
+ Attributes (object)
+ login: `CoolKidO` (string, required)
+ first_name: `Pepa` (string)
+ last_name: `Zdepa` (string)
+ email: `[email protected]` (string)
+ icon: binary
+ Response 404
User with this login does not exist
+ Body
## Current User [/user/me]
Credentials are included in the request and
the server will operate on the user with matching credentials,
if such user exists.
It is up to the client app to display authentication form
when action requiring authentication is invoked and
the current user is not known.
It should then remember the entered credentials
for further requests requiring authentication.
### Show Details [GET]
+ Response 200 (application/json)
The Response looks exactly the same as if GET
using the current users login was called.
However the client app needs to recognize we are
looking at the current user (me), so it should provide
extra buttons for editing and deleting the user.
+ Body
+ Response 403 (application/json)
No user with matching credentials exists
+ Body
### Update User Details [PUT]
+ Response 204
TODO Do we allow editing of user as a whole, by parts...
User updated succesfully
+ Body
+ Response 403
No user with matching credentials exists
+ Body
### Delete User [DELETE]
+ Response 204
User deleted succesfully
+ Body
+ Response 403
No user with matching credentials exists
+ Body
# Group Issues
## New Issue [/issue]
User has to be logged in to report an issue.
The login and password in Basic auth header
will be used to identify the user and the user
will be added as author to the issue.
If incorrect credentials are provided when invoking
this call, the issue will not be persisted.
### Report Issue [POST]
+ Request (application/json)
+ Attributes (object)
+ subject: Stuffs' broke (string, required)
+ description: Detailed description of what is wrong. (string)
+ photo: Base64 encoded PNG (string)
+ category (enum, required)
+ Members
+ Add - Missing benches / trash cans...
+ Remove - ?
+ Repair - Graffiti, street lamps don't work...
+ Complaint - ?
+ Other - User should provide specific description
+ priority (enum, required)
classic MoSCoW, simple enough?
+ Members
+ MustHave
+ ShouldHave
+ CanHave
+ WantToHave
+ location (object) - where the issue is located
+ lat: 37.423021 - latitude (positive or negative)
+ lon: 122.083739 - longitude
+ Response 201
Issue was created
+ Headers
Location: base/uri/to/tracker/issue/new_issue
+ Response 400 (application/json)
+ Attributes (object)
+ errors (array)
+ subject must be filled in (string)
+ selected location is out of bounds (string)
## All Issues [/issue{?filter}]
Everyone can see all issues.
Different clients will want to
### List Issues [GET]
+ Parameters
+ filter: lat:1.91,1.92;lon:2.12,2.14 (string)
Filter can be anything: filter from category,
by author, by location...
It gets parsed by the server, format is TODO
+ Response 200 (application/json)
+ Attributes (array)
+ issue (object)
+ subject: Stuffs' broke (string)
+ description: Detailed description of what is wrong. (string)
+ author: John Doe (string)
+ category (enum) - same domain as in create
+ priority (enum) - same domain as in create
+ status (enum) - modifiable by workers
+ Members
+ Reported
+ Accepted
+ Rejected
+ Fixed
+ location (object) - where the issue is located
+ lat: 37.423021 - latitude
+ lon: 122.083739 - longitude