use URI template syntax in API docs
authorStefan Kögl <stefan@skoegl.net>
Sun, 21 Jul 2013 12:29:27 +0000 (21 14:29 +0200)
committerStefan Kögl <stefan@skoegl.net>
Sun, 21 Jul 2013 12:29:27 +0000 (21 14:29 +0200)
doc/api/reference/devices.rst
doc/api/reference/events.rst
doc/api/reference/settings.rst
doc/api/reference/subscriptions.rst

index 343fd3a..ceb9430 100644 (file)
@@ -26,8 +26,8 @@ Resources
 
 The Devices API defines the following resources ::
 
-    /user/<username>/devices
-    /user/<username>/device/<device-id>
+    /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/<username>/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/<username>/device/<device-id>
+    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/<username>/device/<device-id>
+    POST /user/{username}/device/{device_id}
     Content-Type: application/json
 
     TODO response: return device information
index 4ac37d5..e3ac1aa 100644 (file)
@@ -15,9 +15,9 @@ Resources
 
 The Events API defines the following resources ::
 
-    /user/<username>/events
-    /user/<username>/events/response/<id>
-    /user/<username>/events/device/<device-id>
+    /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/<username>/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/<username>/events?since=<timestamp>
+    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/<username>/device/<device-id>/events
+    GET /user/{username}/device/{device_id}/events
 
 Parameters
 
index af31c50..d3645d8 100644 (file)
@@ -16,10 +16,10 @@ Resources
 
 The Settings API defines the following resources ::
 
-    /user/<username>/settings/account
-    /user/<username>/settings/device
-    /user/<username>/settings/podcast
-    /user/<username>/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/<username>/settings/<scope>?<scope-specification>
-    PATCH /user/<username>/settings/<scope>?<scope-specification>
+    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/<username>/settings/<scope>?<scope-specification>
+    GET /user/{username}/settings/{scope}{?scope_specification}
 
 Scope and specification as above.
 Requires Authentication
index c73c8c5..fc5cf36 100644 (file)
@@ -12,8 +12,8 @@ Resources
 
 The Subscriptions API defines the following resources ::
 
- /user/<username>/subscriptions
- /user/<username>/device/<device-id>/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/<username>/device/<device-id>/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: <https://api.gpodder.net/user/<username>/device/<device-id>/subscription?since=0>; rel=changes
+ Link: <https://api.gpodder.net/user/{username}/device/{deviceid}/subscription?since=0>; 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: <https://api.gpodder.net/user/<username>/device/<device-id>/subscription?since=1234>; rel=changes
+ Link: <https://api.gpodder.net/user/{username}/device/{deviceid}/subscription?since=1234>; rel=changes
 
  no body
 
@@ -103,13 +103,13 @@ Request
 
 Download subscriptions of a device ::
 
- GET /user/<username>/device/<device-id>/subscriptions
+ GET /user/{username}/device/{deviceid}/subscriptions
  Content-Type: application/json
 
 
 Download all of the user's subscriptions ::
 
- GET /user/<username>/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: <https://api.gpodder.net/user/<username>/device/<device-id>/subscription?since=1234>; rel=changes
+ Link: <https://api.gpodder.net/user/{username}/device/{deviceid}/subscription?since=1234>; rel=changes
  Content-Type: application/json
 
  {
@@ -144,7 +144,7 @@ Request
 
 A client can send which podcasts have been subscribed and unsubscribed. ::
 
- POST /user/<username>/device/<device-id>/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/<username>/device/<device-id>/subscriptions?since=<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: <https://api.gpodder.net/user/<username>/device/<device-id>/subscription?since=1234>; rel=changes
+ Link: <https://api.gpodder.net/user/{username}/device/{deviceid}/subscription?since=1234>; rel=changes
  Content-Type: application/json
 
  {