You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.html
+70-19Lines changed: 70 additions & 19 deletions
Original file line number
Diff line number
Diff line change
@@ -24,7 +24,7 @@
24
24
background-color:#f8fafc;
25
25
}
26
26
</style>
27
-
<h1>Amahi Anywhere Client API Specification - v0.12</h1>
27
+
<h1>Amahi Anywhere Client API Specification - v0.13</h1>
28
28
<p>The Amahi Anywhere Clients use a REST HTTP protocol for browsing, downloading and streaming files and more.</p>
29
29
<p>The clients can be in local mode (known as "LAN" or "LAN Access" to the user), or remote mode (known as "Remote"). Internally we just call them local or remote. The client can perform streaming and the rest of the functions much faster when using the local mode, being inside the user's LAN, so that should be the favored mode, when available. The client should test for local mode availability dynamically, but only when the user is interacting with the app, <em>never</em> in the background, as this will be costly in terms of battery.</p>
<li>Authenticate the user against the Amahi API endpoint</li>
45
+
<li>Authenticate the amahi user against the Amahi API endpoint</li>
46
46
<li>GET /servers (this gives a session token to use for each server)</li>
47
+
<li>POST /auth expects JSON type data with pin key in request body and returns auth token for that hda user</li>
47
48
<li>GET /shares will return the visible shares on a given server (with the session for that server)</li>
48
49
<li>GET /files?s=SomeShare&p=/som/path/or/file.png to get a directory or a file from a server (with the proper session key)</li>
49
50
</ol>
50
-
<p>The user navigates their files by repeating calls like 4 above with different share names and paths.</p>
51
+
<p>The user navigates through their files by repeating calls like 5 above with different share names and paths.</p>
51
52
<h2>Authentication</h2>
52
53
<hr/>
53
54
<p>The app must collect 1) a username/email and 2) a password, from the user and authenticate this information against Amahi's servers using the <ahref="http://oauth.net/">OAuth 2 protocol</a> with the <em>Amahi API</em> endpoint.</p>
@@ -100,18 +101,18 @@ <h2>Initial request for Amahi servers</h2>
<p>From this point on, the calls below can be done to the local_addr or the relay_addr.</p>
162
163
<p>If the client is in local mode, the API endpoint is the address given by <code>local_addr</code>. This should be the preferred mode if it's available.</p>
163
164
<p>If the client is in remote mode, the API endpoint is the address given by <code>relay_addr</code>.</p>
165
+
<h3>HDA User Authentication</h3>
166
+
<p>Since different users can have different access permissions on HDA so each user must identify himself/herself to the HDA. In order to do that the app must request a PIN from the user. This PIN can be sent to the HDA either directly or via Proxy.</p>
167
+
<p>To authenticate, the client app has to issue a <code>POST</code> to <code>/auth</code> with an <code>application/json</code> content-type body containing the following in it:</p>
168
+
<ul>
169
+
<li>
170
+
<p><code>POST /auth</code></p>
171
+
<prelang="json"><code> {
172
+
"pin": "1234"
173
+
}
174
+
</code></pre>
175
+
<ul>
176
+
<li>The PIN must be 3 to 5 characters and must match <code>[A-Za-z0-9]+</code>.</li>
177
+
</ul>
178
+
</li>
179
+
<li>
180
+
<p>On successful authentication, a <code>200 OK</code> response will be sent by the server.</p>
<li>This auth_token must be sent in <code>Authorization</code> header for <code>/shares</code>, <code>/files</code> and <code>/logout</code> requests.</li>
187
+
</ul>
188
+
</li>
189
+
<li>
190
+
<p>On unsuccessful authentication, server will respond with <code>401 Unauthorized</code>.</p>
191
+
</li>
192
+
</ul>
193
+
<h3>HDA User Logout</h3>
194
+
<ul>
195
+
<li><code>POST /logout</code></li>
196
+
<li>Logs out the user whose auth_token has been provided and removes its session</li>
197
+
<li>It will return a <code>200 OK</code> response on successful logout</li>
198
+
</ul>
199
+
<h4>Headers</h4>
200
+
<ul>
201
+
<li><strong>Authorization</strong> the <code>auth_token</code> must be sent here.</li>
202
+
</ul>
164
203
<h3>Shares</h3>
165
204
<ul>
166
205
<li>
@@ -176,14 +215,17 @@ <h3>Shares</h3>
176
215
<p>The <code>tags</code> field is a json list of tags associated to a share. The user can put arbitrary information in these fields.</p>
177
216
</li>
178
217
<li>
218
+
<p>The <code>writable</code> field denotes if that share is writable or not for the logged-in user. Client app must appropriately display/hide the Upload or Delete button as per the value of writable field for a given share.</p>
<p>It returns a 200 code if it succeeded, else there is an error</p>
248
290
</li>
249
291
</ul>
292
+
<h4>Headers</h4>
293
+
<ul>
294
+
<li><strong>Authorization</strong> the <code>auth_token</code> must be sent here.</li>
295
+
</ul>
250
296
<h4>Parameters</h4>
251
297
<ul>
252
298
<li><strong>s</strong> is the name of the share where the file is located</li>
@@ -258,6 +304,7 @@ <h4>Parameters</h4>
258
304
</ul>
259
305
<h4>Errors</h4>
260
306
<ul>
307
+
<li>If the <code>Authorization</code> header is not supplied or is wrong, a <code>403 Forbidden</code> is returned.</li>
261
308
<li>If the share does not exist, a <code>400 Bad Request</code> is returned.</li>
262
309
<li>If the path cannot be found, a <code>404 Not Found</code> HTTP error is returned.</li>
263
310
<li>If the path is to a directory, a json representation of all the files and directories therein is returned.</li>
@@ -270,6 +317,10 @@ <h3>Deleting Files</h3>
270
317
<li>Deletes the file or the directory in the given share <code>:sharename</code> in the <code>s</code> parameter, with the given path <code>:path</code> in the <code>p</code> parameter</li>
271
318
<li>It returns a 200 code if it succeeded, else there is an error</li>
272
319
</ul>
320
+
<h4>Headers</h4>
321
+
<ul>
322
+
<li><strong>Authorization</strong> the <code>auth_token</code> must be sent here.</li>
323
+
</ul>
273
324
<h4>Parameters</h4>
274
325
<p>Same parameter as in reading a file, a share and a path to the file.</p>
@@ -147,22 +148,55 @@ If the client is in local mode, the API endpoint is the address given by `local_
147
148
148
149
If the client is in remote mode, the API endpoint is the address given by `relay_addr`.
149
150
151
+
### HDA User Authentication
152
+
153
+
Since different users can have different access permissions on HDA so each user must identify himself/herself to the HDA. In order to do that the app must request a PIN from the user. This PIN can be sent to the HDA either directly or via Proxy.
154
+
155
+
To authenticate, the client app has to issue a `POST` to `/auth` with an `application/json` content-type body containing the following in it:
156
+
157
+
*`POST /auth`
158
+
```json
159
+
{
160
+
"pin": "1234"
161
+
}
162
+
```
163
+
* The PIN must be 3 to 5 characters and must match `[A-Za-z0-9]+`.
164
+
165
+
* On successful authentication, a `200 OK` response will be sent by the server.
166
+
```json
167
+
{
168
+
"auth_token": "51e3088a2da8f1c8b9285f0fae25b95c"
169
+
}
170
+
```
171
+
* This auth_token must be sent in `Authorization` header for `/shares`, `/files` and `/logout` requests.
172
+
* On unsuccessful authentication, server will respond with `401 Unauthorized`.
173
+
174
+
### HDA User Logout
175
+
176
+
* `POST /logout`
177
+
* Logs out the user whose auth_token has been provided and removes its session
178
+
* It will return a `200 OK` response on successful logout
179
+
180
+
#### Headers
181
+
* **Authorization** the `auth_token` must be sent here.
182
+
150
183
### Shares
151
184
152
185
* `GET /shares`
153
186
* Lists all the shares on the HDA that are available to the logged-in user
154
187
* The return type is a json array with a list of shares, sorted alphabetically (without capitalization), with their name as a string in the `name` element, their modification time in the `mtime` element and `tags`.
155
188
* The `tags` field is a json list of tags associated to a share. The user can put arbitrary information in these fields.
189
+
* The `writable` field denotes if that share is writable or not for the logged-in user. Client app must appropriately display/hide the Upload or Delete button as per the value of writable field for a given share.
0 commit comments