@@ -10,12 +10,12 @@ This document provides protocol-level details of the SensorWeb API.
10
10
11
11
All requests will be to URLs of the form:
12
12
13
- https://<host-url>/api/v1 /<api-endpoint>
13
+ https://<host-url>/< api-version> /<api-endpoint>
14
14
15
15
Note that:
16
16
17
17
* All API access must be over a properly-validated HTTPS connection.
18
- * The URL embeds a version identifier "v1"; future revisions of this API may
18
+ * The URL embeds a version identifier "v1.0 "; future revisions of this API may
19
19
introduce new version numbers.
20
20
21
21
## Request Format
@@ -39,7 +39,7 @@ Use the JWT with this header:
39
39
For example:
40
40
41
41
``` curl
42
- curl 'http://localhost:3000/api/v1 /clients' \
42
+ curl 'http://localhost:3000/v1.0 /clients' \
43
43
-H 'Accept: application/json' \
44
44
-H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJraWQiOm51bGwsImFsZyI6IkhTMjU2In0.eyJpZCI6MiwibmFtZSI6ImFkbWluIn0.JNtvokupDl2hdqB+vER15y89qigPc4FviZfJOSR1Vso'
45
45
```
@@ -86,33 +86,40 @@ SHOULD NOT be repeated.
86
86
# API Endpoints
87
87
88
88
* Login
89
- * [ POST /auth/basic] ( #post-authbasic )
90
- * [ GET /auth/facebook] ( #get-authfacebook )
89
+ * [ GET /auth/basic] ( #post-authbasic ) : lock : (client signed token required )
90
+ * [ GET /auth/facebook] ( #get-authfacebook ) : lock : (client signed token required)
91
91
* API clients management
92
92
* [ POST /clients] ( #post-clients ) :lock : (admin scope required)
93
93
* [ GET /clients] ( #get-clients ) :lock : (admin scope required)
94
94
* [ DELETE /clients/: key ] ( #delete-clientskey ) :lock : (admin scope required)
95
95
* Permissions
96
96
* [ GET /permissions] ( #get-permissions ) :lock : (admin scope required)
97
97
98
- ## POST /auth/basic
99
- Authenticates a user using Basic authentication . So far only an admin user is
98
+ ## GET /auth/basic
99
+ Authenticates a user using username and password . So far only an admin user is
100
100
allowed.
101
101
### Request
102
- Requests must include a [ basic authorization header ]
103
- ( https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side )
104
- with ` username:password ` encoded in Base64.
102
+ Requests must include a JWT signed with a valid client secret as the
103
+ ` authToken ` query parameter.
104
+
105
105
``` ssh
106
- POST /api/auth/basic HTTP/1.1
107
- Authorization: Basic YWRtaW46QXZhbGlkUGFzc3dvcmQuMA==
106
+ GET /v1.0/auth/basic?authToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbn
107
+ RJZCI6IjhlYWYxMjQ1MTEzNGIyNGUiLCJ1c2VybmFtZSI6ImFkbWluIiwicGFzc3dvcmQiOiIxLkxv
108
+ bmdhZG1pbnBhc3MuMSIsInNjb3BlcyI6ImFkbWluIn0.foaQeXQGt5_8wFmW5mH9wdQLE3VKHwH9oD
109
+ clmUroWRk HTTP/1.1
108
110
```
111
+
112
+ The payload of the signed JWT must include the following information:
113
+ * ` clientKey ` : client identifier, aka his key.
114
+ * ` scopes ` : the list of permissions the client is asking for for this token.
115
+
109
116
### Response
110
- Successful requests will produce a "201 Created" response with a session token
117
+ Successful requests will produce a 200 response with a session token
111
118
in the form of a [ JWT] ( https://jwt.io/ ) with the following data:
112
119
``` json
113
120
{
114
- "id " : " admin " ,
115
- "scope " : " admin"
121
+ "clientKey " : " 8eaf12451134b24e " ,
122
+ "scopes " : [ " admin" ]
116
123
}
117
124
```
118
125
@@ -124,9 +131,9 @@ Content-Length: 156
124
131
Content-Type: application/json; charset=utf-8
125
132
Date: Fri, 23 Sep 2016 16:22:39 GMT
126
133
{
127
- "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImFk
128
- bWluIiwic2NvcGUiOiJhZG1pbiIsImlhdCI6MTQ3NDY0Nzc1O
129
- X0.R1vQOLVg8A-6i5QaZQVOGAzImiPvgAdkWiODYhYiNn4 "
134
+ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRJZCI6IjhlYWYxMjQ1MTE
135
+ zNGIyNGUiLCJzY29wZXMiOlsiYWRtaW4iXSwiaWF0IjoxNDc0NjQ3NzU5fQ.ZxnRCbuw
136
+ yCypJMnAHHhpwSL_-y19Q4DSioA1cnB9JyY "
130
137
}
131
138
```
132
139
@@ -137,16 +144,16 @@ Requests must include a JWT signed with a valid client secret as the
137
144
` authToken ` query parameter.
138
145
139
146
``` ssh
140
- POST /api /auth/facebook?authToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb
147
+ GET /v1.0 /auth/facebook?authToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb
141
148
GllbnRJZCI6IjEyMzQ1Njc4OTAiLCJzY29wZXMiOlsidXNlci1mYXZvcml0ZXMiXSwiYXV0aFJlZ
142
149
GlyZWN0VXJscyI6WyJodHRwczovL2RvbWFpbi5vcmcvYXV0aC9zdWNjZXNzIl0sImF1dGhGYWlsd
143
150
XJlVXJscyI6WyJodHRwczovL2RvbWFpbi5vcmcvYXV0aC9lcnJvciJdfQ.e7rYEZsQNLG0aTjDRH
144
151
sQ2xembu3fyVe-B9bm8mFprwQ HTTP/1.1
145
152
```
146
153
147
154
The payload of the signed JWT must include the following information:
148
- * ` id ` : client identifier, aka his key.
149
- * ` scope ` : just ` client ` for now .
155
+ * ` clientKey ` : client identifier, aka his key.
156
+ * ` scopes ` : the list of permissions the client is asking for for this token .
150
157
* ` redirectUrl ` : the URL you would like to be redirected after a
151
158
successful login. This URL needs to be associated with your client
152
159
information first. It will gets the user's JWT as a query parameter ` token ` .
@@ -172,12 +179,8 @@ with the following data:
172
179
173
180
``` json
174
181
{
175
- "id" : {
176
- "opaqueId" : " facebook_id" ,
177
- "provider" : " facebook" ,
178
- "clientKey" : " 02e9c791d7"
179
- },
180
- "scope" : " user"
182
+ "clientKey" : " 02e9c791d7" ,
183
+ "scopes" : [" sensorthings" ]
181
184
}
182
185
```
183
186
@@ -191,7 +194,7 @@ ___Parameters___
191
194
* permissions (optional) - List of permissions the client is allowed to request.
192
195
193
196
``` ssh
194
- POST /api /clients HTTP/1.1
197
+ POST /v1.0 /clients HTTP/1.1
195
198
Content-Type: application/json
196
199
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImFkbWluIiwic2NvcGUiOiJhZG1pbiIsImlhdCI6MTQ3NDY0Nzc1OX0.R1vQOLVg8A-6i5QaZQVOGAzImiPvgAdkWiODYhYiNn4
197
200
{
@@ -222,7 +225,7 @@ Get the list of registered API clients.
222
225
223
226
### Request
224
227
``` ssh
225
- GET /api /clients HTTP/1.1
228
+ GET /v1.0 /clients HTTP/1.1
226
229
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImFkbWluIiwic2NvcGUiOiJhZG1pbiIsImlhdCI6MTQ3NDY0Nzc1OX0.R1vQOLVg8A-6i5QaZQVOGAzImiPvgAdkWiODYhYiNn4
227
230
```
228
231
@@ -250,7 +253,7 @@ Deletes a registered API client given its identifier.
250
253
251
254
### Request
252
255
``` ssh
253
- DELETE /api /clients/766a06dab7358b6aec17891df1fe8555 HTTP/1.1
256
+ DELETE /v1.0 /clients/766a06dab7358b6aec17891df1fe8555 HTTP/1.1
254
257
Host: localhost:8080
255
258
```
256
259
@@ -262,7 +265,7 @@ Get the list of client permissions.
262
265
263
266
### Request
264
267
``` ssh
265
- GET /api /permissions HTTP/1.1
268
+ GET /v1.0 /permissions HTTP/1.1
266
269
Host: localhost:8080
267
270
```
268
271
0 commit comments