work on API 3 draft
authorStefan Kögl <stefan@skoegl.net>
Sat, 13 Jul 2013 18:22:47 +0000 (13 20:22 +0200)
committerStefan Kögl <stefan@skoegl.net>
Sat, 13 Jul 2013 18:22:47 +0000 (13 20:22 +0200)
doc/api/index.rst
doc/api/reference/directory.rst
doc/api/reference/general.rst
doc/api/reference/user.rst
doc/api/usage.rst

index ececa78..aa889d5 100644 (file)
@@ -6,9 +6,13 @@
 API 3 Documentation (draft)
 ===========================
 
-This site contains drafts for the gpodder.net's future API -- version 3 --
+*This site contains drafts for the gpodder.net's future API -- version 3 --
 which is not yet implemented.  The current API is documented at
-http://wiki.gpodder.org/wiki/Web_Services/API_2.
+http://wiki.gpodder.org/wiki/Web_Services/API_2.*
+
+The gpodder.net API allows clients to interact with gpodder.net. The API is
+provided via a REST interface, and is free of charge within certain quotas, and
+completely free for open source clients (see :ref:`usage`).
 
 Contents
 --------
index 82f628e..843af85 100644 (file)
@@ -16,75 +16,228 @@ The Directory API defines the following resources ::
     /search/podcasts
     /directory/toplist
     /directory/tags/latest
-    /directory/tag/<tag>
+    /directory/tag/{tag}
+    /user/{username}/suggestions
 
 
 Podcast Toplist
 ---------------
 
+The podcast toplist ranks podcasts by their number of subscribers.
+
+
+Parameters
+^^^^^^^^^^
+
+* **lang**: a ISO 639-1 (two-letter) language code. If given, only podcasts in
+  this language are returned. If omitted, no language restriction is made.
+
+Request
+^^^^^^^
+
 Get the toplist ::
 
-    GET /directory/toplist
+    GET /directory/toplist{?lang:2}
     Content-Tpe: application/json
 
 
-Response ::
+Response
+^^^^^^^^
+
+The response contains a ``toplist`` member which has a list of
+:ref:`podcast-type` objects. The first entry in the list represents the highest
+ranking podcast in the toplist. If a ``lang`` parameter was included in the
+request, it is also included in the response. ::
 
     200 OK
     Content-Tpe: application/json
 
-    TODO: body
+    {
+        "toplist": [
+            podcast1,
+            podcast2,
+            podcast3,
+            ...
+        ],
+        "lang": "en"
+    }
 
 
 Podcast Search
 --------------
 
-Parameters:
+Parameters
+^^^^^^^^^^
 
 * **q**: query string (mandatory)
 
 
-Request ::
+Request
+^^^^^^^
 
-    GET /search/podcasts?q=linux
+The search query is provided as a GET parameter. ::
+
+    GET /search/podcasts{?q}
     Content-Tpe: application/json
 
 
-Response ::
+Responses
+^^^^^^^^^
+
+If the search could be performed, the search results (if any) are returned in
+the ``search`` member. The query is returned in the ``query`` member. ::
 
     200 OK
+    Content-Type: application/json
+
+    {
+        "search": [
+            podcast1,
+            podcast2,
+            ...
+        ],
+        "query": "query text"
+    }
+
+
+If the search could not be performed, for example because the query was
+missing ::
+
+    400 Bad Request
+    Content-Type: application/json
+
+    {
+        "message": "parameter q missing",
+        "errors": [
+            {
+                field: "?q",
+                code: "parameter_missing"
+            }
+        ]
+    }
+
+
+Example
+^^^^^^^
+
+Example::
+
+    GET /search/podcasts?q=linux
     Content-Tpe: application/json
 
-    TODO: body
+
+    200 OK
+    Content-Tpe: application/json
+
+    {
+        "search": [
+            { "url": "http://example.com/feed.rss", ...},
+            { ... },
+            ...
+        ],
+        "query": "linux"
+    }
+
 
 
 Latest Tags
 -----------
 
-Parameters:
+The "Latest Tags" endpoint returns *current* tags. Those are tags for which
+podcasts have recently published a new episode.
+
+Parameters
+^^^^^^^^^^
 
 * **num**: number of tags to return (optional, default: 10)
 
 
-Request ::
+Request
+^^^^^^^
+
+The number of tags to return can be included in the request. ::
 
-    GET /directory/tags/latest
+    GET /directory/tags/latest{?num}
     Content-Tpe: application/json
 
 
-Response ::
+Reponse
+^^^^^^^
+
+In the ``tags`` member a list of :ref:`tag-type` objects is provided. ::
 
     200 OK
     Content-Tpe: application/json
+    Link: <https://api.gpodder.net/3/directory/tag/{label}>; rel="https://api.gpodder.net/3/relation/tag-podcasts"; title="Podcasts for tag {label}"
 
-    TODO: body
+    {
+        "tags": [
+            { "label": "Technology" },
+            { ... },
+            ...
+        ]
+    }
+
+Clients can use the provided ``Link`` header and resolve the `URI template
+<http://tools.ietf.org/html/rfc6570>`_ to obtain the URL for retrieving the
+podcasts of a certain tag.
 
 
 Podcasts for Tag
 ----------------
 
+Clients can retrieve podcasts for a given tag.
+
+
+Request
+^^^^^^^
+
+Request. ::
+
+    GET /directory/tag/{tag}
+    Content-Tpe: application/json
+
+
+Response
+^^^^^^^^
+
+Response. ::
+
+    200 OK
+    Content-Tpe: application/json
+
+    TODO: body
+
 
 Podcast Suggestions
 -------------------
 
+Clients can retrieve suggested podcasts for the current user.
+
+
+Request
+^^^^^^^
+
+Request. ::
+
+    GET /user/{username}/suggestions
+    Content-Tpe: application/json
+
+
+
+Response
+^^^^^^^^
+
+The response contains a ``suggestions`` member which has a list of
+:ref:`podcast-type` objects. ::
+
+    200 OK
+    Content-Tpe: application/json
 
+    {
+        "suggestions": [
+            { podcast1 },
+            { podcast2 },
+            ...
+        ]
+    }
index 5f3eca3..fcc10d1 100644 (file)
@@ -5,7 +5,7 @@ The API can be accessed via http and https. https is preferable from a security
 / privacy point of view and should be used by all clients. gpodder.net also
 seems to be blocked in China via plain http.
 
-All endpoints are offered at https://api.gpodder.net/3/.
+All endpoints are relative to https://api.gpodder.net/3/.
 
 
 * Request and Response Formats: JSON
@@ -23,8 +23,13 @@ TODO: see `URI Templates <http://tools.ietf.org/html/rfc6570>`_
 Status Codes
 ------------
 
-The following status codes can be returned for any API request. Most resources
-will, however, define additional status codes.
+The API uses HTTP status codes to inform clients about type of response. The
+semantics are used according to `their specified semantics
+<http://www.iana.org/assignments/http-status-codes/>`_.
+
+The specification of each API endpoint describes which status codes should be
+expected. In addition the following status codes can be returned for any API
+request.
 
 +----------------------------+-----------------------------------------------+
 | Status Code                | Interpretation                                |
@@ -71,11 +76,22 @@ The ``errors`` array contains objects with the following information ::
         code: "<error code>"
     }
 
-In ``field`` a `JSON Pointer <http://tools.ietf.org/html/rfc6901>`_ to the
-problematic field in the request is provided. The ``code`` describes the actual
-error. The following error codes are defined:
+The ``field`` value indicates where the error occured.
+
+* If the value starts with a ``/``, it should be interpreted as a `JSON Pointer
+  <http://tools.ietf.org/html/rfc6901>`_ to the problematic field in the
+  request body.
+
+* If the value starts with a ``?``, it is followed by the name of the parameter
+  that was responsible for the error.
+
+* The value can be null, indicating that the error was not caused by a specific
+  field.
+
+The ``code`` describes the actual error. The following error codes are defined:
 
 * ``ìnvalid_url``: The provided values is not a valid URL.
+* ``parameter_missing``: A mandatory parameter was not provided.
 
 Error codes may be added on demand. Clients should therefore expect and accept
 arbitrary string values.
@@ -155,3 +171,27 @@ member. ::
         title: "Cool Podcast",
         logo: "http://example.com/podcast-logo.png"
     }
+
+
+.. _tag-type:
+
+Tag
+^^^
+
+A tag is represented as a JSON object containing at least a ``label``
+member. ::
+
+    {
+        "label": "Technology"
+    }
+
+
+Relations
+---------
+
+`Relation types <http://tools.ietf.org/html/rfc5988#section-5.3>`_ that are
+used in the API:
+
+* ``https://api.gpodder.net/3/relation/tag-podcasts``: podcasts for a given tag
+
+TODO: should they be on domain api.gpodder.net, or just gpodder.net?
index 7501e34..0a637db 100644 (file)
@@ -4,13 +4,16 @@ User API
 The User API can be used to retrieve public information about a user, and to
 discover user-related resources.
 
+When initiating a session, a client SHOULD query the user information, to
+discover URIs for further queries.
+
 
 Resources
 ---------
 
 The User API defines the following resources ::
 
-  /user/<username>
+  /user/{username}
 
 
 Get User Info
@@ -18,7 +21,7 @@ Get User Info
 
 Request ::
 
-    GET /user/<username>
+    GET /user/{username}
     Content-Tpe: application/json
 
 
@@ -35,7 +38,7 @@ Response::
         "flattr_username": "stefankoegl",
 
         "resources": {
-            "subscriptions": "http://api.gpodder.net/stefan/subscriptions",
+            "subscriptions": "http://api.gpodder.net/3/user/{username}/subscriptions",
             ...
         }
     }
index 4afac1e..d97ed5d 100644 (file)
@@ -1,15 +1,22 @@
+.. _usage:
+
 API Usage
 =========
 
+This page describes how the gpodder.net API can be used.
+
 
 Client Registration
 -------------------
 
 Most API endpoints can only be accessed by registered clients using a client
-key. Clients can be registered for free at LINK.
+key. Clients can be registered for free at LINK. A registration needs to be
+approved before it can be used.
 
 TODO: User-Agent?
 
+TODO: how is the API Key included in requests?
+
 
 Allowed Usage
 -------------
@@ -29,7 +36,9 @@ certain feature.
 +------------------------+---------------+----------------+
 | Features               | Open source   | Closed source  |
 +========================+===============+================+
-| Podcast Search         | unlimited     | unlimited      |
+| Base Quota             | unlimited     | 1000           |
++------------------------+---------------+----------------+
+| Podcast Search         | unlimited     | not counted    |
 +------------------------+---------------+----------------+
 | Podcast Toplist        | unlimited     | +1000          |
 +------------------------+---------------+----------------+
@@ -45,7 +54,7 @@ certain feature.
 +------------------------+---------------+----------------+
 | Episode Favorites      | unlimited     | +1000          |
 +------------------------+---------------+----------------+
-| Authentication         | unlimited     | unlimited      |
+| Authentication         | unlimited     | not counted    |
 +------------------------+---------------+----------------+
 | Device Sync            | unlimited     | +1000          |
 +------------------------+---------------+----------------+