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 relative to 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 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/>`_.
  29
  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
  32 request.
  33
  34 +----------------------------+-----------------------------------------------+
  35 | Status Code                | Interpretation                                |
  36 +============================+===============================================+
  37 | 200 OK                     | All OK                                        |
  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 +----------------------------+-----------------------------------------------+
  52
  53 * Request not allowed (eg quota, authentication, permissions, etc)
  54
  55
  56 Responses
  57 ---------
  58
  59 All responses are valid JSON (unless otherwise stated).
  60
  61
  62 Error messages
  63 --------------
  64
  65 TODO: review `Problem Details for HTTP APIs
  66 <http://tools.ietf.org/html/draft-nottingham-http-problem>`_
  67
  68 An error response looks like ::
  69
  70     { message: "message", errors: [...] }
  71
  72 The ``errors`` array contains objects with the following information ::
  73
  74     {
  75         field: "<JSON Pointer to field>",
  76         code: "<error code>"
  77     }
  78
  79 The ``field`` value indicates where the error occured.
  80
  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
  83   request body.
  84
  85 * If the value starts with a ``?``, it is followed by the name of the parameter
  86   that was responsible for the error.
  87
  88 * The value can be null, indicating that the error was not caused by a specific
  89   field.
  90
  91 The ``code`` describes the actual error. The following error codes are defined:
  92
  93 * ``ìnvalid_url``: The provided values is not a valid URL.
  94 * ``parameter_missing``: A mandatory parameter was not provided.
  95
  96 Error codes may be added on demand. Clients should therefore expect and accept
  97 arbitrary string values.
  98
  99
 100 Redirects
 101 ---------
 102
 103 permanent (301) vs temporary (302, 307) redirects.
 104
 105
 106 Authentication
 107 --------------
 108
 109 See Authentication API
 110
 111
 112
 113 Rate Limiting
 114 -------------
 115
 116 See usage quotas ::
 117
 118     GET /rate_limit
 119
 120     HTTP/1.1 200 OK
 121     Status: 200 OK
 122     X-RateLimit-Limit: 60
 123     X-RateLimit-Remaining: 56
 124
 125 What counts as request? conditional requests?
 126
 127
 128
 129 Conditional Requests
 130 --------------------
 131
 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.
 138
 139
 140 Formats
 141 -------
 142
 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.
 146
 147
 148 JSONP Callbacks
 149 ^^^^^^^^^^^^^^^
 150
 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.
 156
 157
 158 Resource Types
 159 --------------
 160
 161 .. _podcast-type:
 162
 163 Podcast
 164 ^^^^^^^
 165
 166 A podcast is represented as a JSON object containing at least an ``url``
 167 member. ::
 168
 169     {
 170         url: "http://example.com/podcast.rss",
 171         title: "Cool Podcast",
 172         logo: "http://example.com/podcast-logo.png"
 173     }
 174
 175
 176 .. _tag-type:
 177
 178 Tag
 179 ^^^
 180
 181 A tag is represented as a JSON object containing at least a ``label``
 182 member. ::
 183
 184     {
 185         "label": "Technology"
 186     }
 187
 188
 189 Relations
 190 ---------
 191
 192 `Relation types <http://tools.ietf.org/html/rfc5988#section-5.3>`_ that are
 193 used in the API:
 194
 195 * ``https://api.gpodder.net/3/relation/tag-podcasts``: podcasts for a given tag
 196
 197 TODO: should they be on domain api.gpodder.net, or just gpodder.net?