From: Stefan Kögl Date: Sun, 21 Jul 2013 12:29:27 +0000 (+0200) Subject: use URI template syntax in API docs X-Git-Url: https://repo.or.cz/w/mygpo.git/commitdiff_plain/2d37440cb049b5eccdae87f0a34a889ea6ad89cf use URI template syntax in API docs --- diff --git a/doc/api/reference/devices.rst b/doc/api/reference/devices.rst index 343fd3a5..ceb9430e 100644 --- a/doc/api/reference/devices.rst +++ b/doc/api/reference/devices.rst @@ -26,8 +26,8 @@ Resources The Devices API defines the following resources :: - /user//devices - /user//device/ + /user/{username}/devices + /user/{username}/device/{device_id} Retrieve Device List @@ -35,7 +35,7 @@ Retrieve Device List Retrieve the list of existing devices :: - GET /user//devices + GET /user/{username}/devices Content-Type: application/json 200 OK @@ -59,7 +59,7 @@ Get Device Information Retrieve information about a specific device :: - GET /user//device/ + GET /user/{username}/device/{device_id} Content-Type: application/json 200 OK @@ -80,7 +80,7 @@ Update Device Information Update the information of a device :: - POST /user//device/ + POST /user/{username}/device/{device_id} Content-Type: application/json TODO response: return device information diff --git a/doc/api/reference/events.rst b/doc/api/reference/events.rst index 4ac37d50..e3ac1aa8 100644 --- a/doc/api/reference/events.rst +++ b/doc/api/reference/events.rst @@ -15,9 +15,9 @@ Resources The Events API defines the following resources :: - /user//events - /user//events/response/ - /user//events/device/ + /user/{username}/events + /user/{username}/events/response/{id} + /user/{username}/events/device/{device_id} Event Data @@ -80,7 +80,7 @@ Request To initiate an upload, the following request should be issued. :: - POST /user//events + POST /user/{username}/events Content-Tpe: application/json { @@ -150,7 +150,7 @@ server maintains a timestamp per device). **Explicit Timestamp:** retrieve all events after a specific timestamp. :: - GET /user//events?since= + GET /user/{username}/events{?since} Parameters @@ -160,7 +160,7 @@ Parameters **Implicit Timestamp:** retrieve all events that the current device has not yet seen. The timestamp of is stored on the server side. :: - GET /user//device//events + GET /user/{username}/device/{device_id}/events Parameters diff --git a/doc/api/reference/settings.rst b/doc/api/reference/settings.rst index af31c509..d3645d8f 100644 --- a/doc/api/reference/settings.rst +++ b/doc/api/reference/settings.rst @@ -16,10 +16,10 @@ Resources The Settings API defines the following resources :: - /user//settings/account - /user//settings/device - /user//settings/podcast - /user//settings/episode + /user/{username}/settings/account + /user/{username}/settings/device + /user/{username}/settings/podcast + /user/{username}/settings/episode Well-Known Settings @@ -86,8 +86,8 @@ Saving Settings Save Settings :: - POST /user//settings/? - PATCH /user//settings/? + POST /user/{username}/settings/{scope}{?scope_specification} + PATCH /user/{username}/settings/{scope}{?scope_specification} * Requires authentication @@ -170,7 +170,7 @@ Get Settings Get Settings :: - GET /user//settings/? + GET /user/{username}/settings/{scope}{?scope_specification} Scope and specification as above. Requires Authentication diff --git a/doc/api/reference/subscriptions.rst b/doc/api/reference/subscriptions.rst index c73c8c59..fc5cf369 100644 --- a/doc/api/reference/subscriptions.rst +++ b/doc/api/reference/subscriptions.rst @@ -12,8 +12,8 @@ Resources The Subscriptions API defines the following resources :: - /user//subscriptions - /user//device//subscriptions + /user/{username}/subscriptions + /user/{username}/device/{deviceid}/subscriptions Subscription Upload @@ -29,7 +29,7 @@ Request The client sends an object containing all current subscriptions for the device. :: - PUT /user//device//subscriptions + PUT /user/{username}/device/{deviceid}/subscriptions Content-Type: application/json { @@ -52,7 +52,7 @@ retrieve changes to the subscriptions since the respective response (see If a new device has been created :: 201 Created - Link: /device//subscription?since=0>; rel=changes + Link: ; rel=changes no body @@ -60,7 +60,7 @@ If a new device has been created :: If the subscriptions have been processed immediatelly :: 204 No Content - Link: /device//subscription?since=1234>; rel=changes + Link: ; rel=changes no body @@ -103,13 +103,13 @@ Request Download subscriptions of a device :: - GET /user//device//subscriptions + GET /user/{username}/device/{deviceid}/subscriptions Content-Type: application/json Download all of the user's subscriptions :: - GET /user//subscriptions + GET /user/{username}/subscriptions Content-Type: application/json @@ -119,7 +119,7 @@ Response The podcasts correspond to the :ref:`podcast-type` type. :: 200 OK - Link: /device//subscription?since=1234>; rel=changes + Link: ; rel=changes Content-Type: application/json { @@ -144,7 +144,7 @@ Request A client can send which podcasts have been subscribed and unsubscribed. :: - POST /user//device//subscriptions + POST /user/{username}/device/{deviceid}/subscriptions Content-Tpe: application/json { @@ -157,7 +157,8 @@ A client can send which podcasts have been subscribed and unsubscribed. :: } A client MUST NOT upload a change set where both ``subscribe`` and -``unsubscribe`` are empty. +``unsubscribe`` are empty, or where the same podcast is given in both +``subscribe`` and ``unsubscribe``. Response @@ -195,7 +196,7 @@ Request The client makes the following request. :: - GET /user//device//subscriptions?since= + GET /user/{username}/device/{deviceid}/subscriptions{?since} Content-Tpe: application/json @@ -207,7 +208,7 @@ The server can response with any of the following status codes. The changes are returned immediatelly. :: 200 OK - Link: /device//subscription?since=1234>; rel=changes + Link: ; rel=changes Content-Type: application/json {