From 2b22c2a8d481f4bdb8a48d909add9cc291879b69 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Stefan=20K=C3=B6gl?= Date: Sat, 13 Jul 2013 20:22:47 +0200 Subject: [PATCH] work on API 3 draft --- doc/api/index.rst | 8 +- doc/api/reference/directory.rst | 181 ++++++++++++++++++++++++++++++++++++---- doc/api/reference/general.rst | 52 ++++++++++-- doc/api/reference/user.rst | 9 +- doc/api/usage.rst | 15 +++- 5 files changed, 237 insertions(+), 28 deletions(-) diff --git a/doc/api/index.rst b/doc/api/index.rst index ececa788..aa889d58 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -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 -------- diff --git a/doc/api/reference/directory.rst b/doc/api/reference/directory.rst index 82f628ee..843af855 100644 --- a/doc/api/reference/directory.rst +++ b/doc/api/reference/directory.rst @@ -16,75 +16,228 @@ The Directory API defines the following resources :: /search/podcasts /directory/toplist /directory/tags/latest - /directory/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: ; 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 +`_ 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 }, + ... + ] + } diff --git a/doc/api/reference/general.rst b/doc/api/reference/general.rst index 5f3eca34..fcc10d1d 100644 --- a/doc/api/reference/general.rst +++ b/doc/api/reference/general.rst @@ -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 `_ 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 +`_. + +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: "" } -In ``field`` a `JSON Pointer `_ 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 + `_ 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 `_ 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? diff --git a/doc/api/reference/user.rst b/doc/api/reference/user.rst index 7501e34b..0a637dbe 100644 --- a/doc/api/reference/user.rst +++ b/doc/api/reference/user.rst @@ -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/ + /user/{username} Get User Info @@ -18,7 +21,7 @@ Get User Info Request :: - GET /user/ + 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", ... } } diff --git a/doc/api/usage.rst b/doc/api/usage.rst index 4afac1e3..d97ed5df 100644 --- a/doc/api/usage.rst +++ b/doc/api/usage.rst @@ -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 | +------------------------+---------------+----------------+ -- 2.11.4.GIT