4 The API can be accessed via http and https. https is preferable from a security
5 / privacy point of view and should be used by all clients. gpodder.net also
6 seems to be blocked in China via plain http.
8 All endpoints are relative to https://api.gpodder.net/3/.
11 * Request and Response Formats: JSON
12 * JSONP also available
13 * Date format: ISO 8601 / `RFC 3339 <http://tools.ietf.org/html/rfc3339>`_
14 ``YYYY-MM-DDTHH:MM:SSZ``
16 Podcast is identified by its feed URL, episode is identified by its media URL.
18 TODO: see http://developer.github.com/v3/ for relevant information!
20 TODO: see `URI Templates <http://tools.ietf.org/html/rfc6570>`_
26 The API uses HTTP status codes to inform clients about type of response. The
27 semantics are used according to `their specified semantics
28 <http://www.iana.org/assignments/http-status-codes/>`_.
30 The specification of each API endpoint describes which status codes should be
31 expected. In addition the following status codes can be returned for any API
34 +----------------------------+-----------------------------------------------+
35 | Status Code | Interpretation |
36 +============================+===============================================+
38 +----------------------------+-----------------------------------------------+
39 | 301 Moved Permanently | The resource has moved permanently to the |
40 | | location provided in the Location header. |
41 | | Subsequent requests should use the new |
42 | | location directly. |
43 +----------------------------+-----------------------------------------------+
44 | 303 See Other | the response to the request is found at the |
45 | | location provided in the Location header. It |
46 | | should be retrieved using a GET request |
47 +----------------------------+-----------------------------------------------+
48 | 400 Bad Request | invalid JSON, invalid types |
49 +----------------------------+-----------------------------------------------+
50 | 503 Service Unavailable | The service and/or API are under maintenance |
51 +----------------------------+-----------------------------------------------+
53 * Request not allowed (eg quota, authentication, permissions, etc)
59 All responses are valid JSON (unless otherwise stated).
65 TODO: review `Problem Details for HTTP APIs
66 <http://tools.ietf.org/html/draft-nottingham-http-problem>`_
68 An error response looks like ::
70 { message: "message", errors: [...] }
72 The ``errors`` array contains objects with the following information ::
75 field: "<JSON Pointer to field>",
79 The ``field`` value indicates where the error occured.
81 * If the value starts with a ``/``, it should be interpreted as a `JSON Pointer
82 <http://tools.ietf.org/html/rfc6901>`_ to the problematic field in the
85 * If the value starts with a ``?``, it is followed by the name of the parameter
86 that was responsible for the error.
88 * The value can be null, indicating that the error was not caused by a specific
91 The ``code`` describes the actual error. The following error codes are defined:
93 * ``ìnvalid_url``: The provided values is not a valid URL.
94 * ``parameter_missing``: A mandatory parameter was not provided.
96 Error codes may be added on demand. Clients should therefore expect and accept
97 arbitrary string values.
103 permanent (301) vs temporary (302, 307) redirects.
109 See Authentication API
122 X-RateLimit-Limit: 60
123 X-RateLimit-Remaining: 56
125 What counts as request? conditional requests?
132 Some responses return ``Last-Modified`` and ``ETag`` headers. Clients SHOULD
133 use the values of these headers to make subsequent requests to those resources
134 using the ``If-Modified-Since`` and ``If-None-Match`` headers, respectively. If
135 the resource has not changed, the server will return a ``304 Not Modified``.
136 Making a conditional request and receiving a 304 response does not count
137 against the rate limit.
143 All data is exchanged as `JSON <http://tools.ietf.org/html/rfc4627>`_. All
144 resources are represented as JSON objects, and requests are expected as also
145 expected to contain JSON objects.
151 You can pass a ``?callback=<function-name>`` parameter to any GET call to have
152 the results wrapped in a JSON function. This is typically used when browsers
153 want to embed content received from the API in web pages by getting around
154 cross domain issues. The response includes the same data output as the regular
155 API, plus the relevant HTTP Header information.
166 A podcast is represented as a JSON object containing at least an ``url``
170 url: "http://example.com/podcast.rss",
171 title: "Cool Podcast",
172 logo: "http://example.com/podcast-logo.png"
181 A tag is represented as a JSON object containing at least a ``label``
185 "label": "Technology"
192 `Relation types <http://tools.ietf.org/html/rfc5988#section-5.3>`_ that are
195 * ``https://api.gpodder.net/3/relation/tag-podcasts``: podcasts for a given tag
197 TODO: should they be on domain api.gpodder.net, or just gpodder.net?