doc/api/reference/general.rst

   1 General Information
   2 ===================
   3
   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.
   7
   8 All endpoints are offered at https://api.gpodder.net/3/.
   9
  10
  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``
  15
  16 Podcast is identified by its feed URL, episode is identified by its media URL.
  17
  18 TODO: see http://developer.github.com/v3/ for relevant information!
  19
  20 TODO: see `URI Templates <http://tools.ietf.org/html/rfc6570>`_
  21
  22
  23 Status Codes
  24 ------------
  25
  26 The following status codes can be returned for any API request. Most resources
  27 will, however, define additional status codes.
  28
  29 +----------------------------+-----------------------------------------------+
  30 | Status Code                | Interpretation                                |
  31 +============================+===============================================+
  32 | 200 OK                     | All OK                                        |
  33 +----------------------------+-----------------------------------------------+
  34 | 301 Moved Permanently      | The resource has moved permanently to the     |
  35 |                            | location provided in the Location header.     |
  36 |                            | Subsequent requests should use the new        |
  37 |                            | location directly.                            |
  38 +----------------------------+-----------------------------------------------+
  39 | 303 See Other              | the response to the request is found at the   |
  40 |                            | location provided in the Location header. It  |
  41 |                            | should be retrieved using a GET request       |
  42 +----------------------------+-----------------------------------------------+
  43 | 400 Bad Request            | invalid JSON, invalid types                   |
  44 +----------------------------+-----------------------------------------------+
  45 | 503 Service Unavailable    | The service and/or API are under maintenance  |
  46 +----------------------------+-----------------------------------------------+
  47
  48 * Request not allowed (eg quota, authentication, permissions, etc)
  49
  50
  51 Responses
  52 ---------
  53
  54 All responses are valid JSON (unless otherwise stated).
  55
  56
  57 Error messages
  58 --------------
  59
  60 TODO: review `Problem Details for HTTP APIs
  61 <http://tools.ietf.org/html/draft-nottingham-http-problem>`_
  62
  63 An error response looks like ::
  64
  65     { message: "message", errors: [...] }
  66
  67 The ``errors`` array contains objects with the following information ::
  68
  69     {
  70         field: "<JSON Pointer to field>",
  71         code: "<error code>"
  72     }
  73
  74 In ``field`` a `JSON Pointer <http://tools.ietf.org/html/rfc6901>`_ to the
  75 problematic field in the request is provided. The ``code`` describes the actual
  76 error. The following error codes are defined:
  77
  78 * ``ìnvalid_url``: The provided values is not a valid URL.
  79
  80 Error codes may be added on demand. Clients should therefore expect and accept
  81 arbitrary string values.
  82
  83
  84 Redirects
  85 ---------
  86
  87 permanent (301) vs temporary (302, 307) redirects.
  88
  89
  90 Authentication
  91 --------------
  92
  93 See Authentication API
  94
  95
  96
  97 Rate Limiting
  98 -------------
  99
 100 See usage quotas ::
 101
 102     GET /rate_limit
 103
 104     HTTP/1.1 200 OK
 105     Status: 200 OK
 106     X-RateLimit-Limit: 60
 107     X-RateLimit-Remaining: 56
 108
 109 What counts as request? conditional requests?
 110
 111
 112
 113 Conditional Requests
 114 --------------------
 115
 116 Some responses return ``Last-Modified`` and ``ETag`` headers. Clients SHOULD
 117 use the values of these headers to make subsequent requests to those resources
 118 using the ``If-Modified-Since`` and ``If-None-Match`` headers, respectively. If
 119 the resource has not changed, the server will return a ``304 Not Modified``.
 120 Making a conditional request and receiving a 304 response does not count
 121 against the rate limit.
 122
 123
 124 Formats
 125 -------
 126
 127 All data is exchanged as `JSON <http://tools.ietf.org/html/rfc4627>`_. All
 128 resources are represented as JSON objects, and requests are expected as also
 129 expected to contain JSON objects.
 130
 131
 132 JSONP Callbacks
 133 ^^^^^^^^^^^^^^^
 134
 135 You can pass a ``?callback=<function-name>`` parameter to any GET call to have
 136 the results wrapped in a JSON function. This is typically used when browsers
 137 want to embed content received from the API in web pages by getting around
 138 cross domain issues. The response includes the same data output as the regular
 139 API, plus the relevant HTTP Header information.
 140
 141
 142 Resource Types
 143 --------------
 144
 145 .. _podcast-type:
 146
 147 Podcast
 148 ^^^^^^^
 149
 150 A podcast is represented as a JSON object containing at least an ``url``
 151 member. ::
 152
 153     {
 154         url: "http://example.com/podcast.rss",
 155         title: "Cool Podcast",
 156         logo: "http://example.com/podcast-logo.png"
 157     }