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 * ``duplicate_list_name``: A podcast list with the same name already exists.
  96 * ``user_does_not_exist``: the specified user does not exist.
  97 * ``podcastlist_does_not_exist``: the specified podcast list does not exist.
  98
  99 Error codes may be added on demand. Clients should therefore expect and accept
 100 arbitrary string values.
 101
 102
 103 Redirects
 104 ---------
 105
 106 permanent (301) vs temporary (302, 307) redirects.
 107
 108
 109 Authentication
 110 --------------
 111
 112 See Authentication API
 113
 114
 115
 116 Rate Limiting
 117 -------------
 118
 119 See usage quotas ::
 120
 121     GET /rate_limit
 122
 123     HTTP/1.1 200 OK
 124     Status: 200 OK
 125     X-RateLimit-Limit: 60
 126     X-RateLimit-Remaining: 56
 127
 128 What counts as request? conditional requests?
 129
 130
 131
 132 Conditional Requests
 133 --------------------
 134
 135 Some responses return ``Last-Modified`` and ``ETag`` headers. Clients SHOULD
 136 use the values of these headers to make subsequent requests to those resources
 137 using the ``If-Modified-Since`` and ``If-None-Match`` headers, respectively. If
 138 the resource has not changed, the server will return a ``304 Not Modified``.
 139 Making a conditional request and receiving a 304 response does not count
 140 against the rate limit.
 141
 142
 143 Formats
 144 -------
 145
 146 All data is exchanged as `JSON <http://tools.ietf.org/html/rfc4627>`_. All
 147 resources are represented as JSON objects, and requests are expected as also
 148 expected to contain JSON objects.
 149
 150
 151 JSONP Callbacks
 152 ^^^^^^^^^^^^^^^
 153
 154 You can pass a ``?callback=<function-name>`` parameter to any GET call to have
 155 the results wrapped in a JSON function. This is typically used when browsers
 156 want to embed content received from the API in web pages by getting around
 157 cross domain issues. The response includes the same data output as the regular
 158 API, plus the relevant HTTP Header information.
 159
 160
 161 Resource Types
 162 --------------
 163
 164 .. _podcast-type:
 165
 166 Podcast
 167 ^^^^^^^
 168
 169 A podcast is represented as a JSON object containing at least an ``url``
 170 member. ::
 171
 172     {
 173         url: "http://example.com/podcast.rss",
 174         title: "Cool Podcast",
 175         logo: "http://example.com/podcast-logo.png"
 176     }
 177
 178
 179 .. _tag-type:
 180
 181 Tag
 182 ^^^
 183
 184 A tag is represented as a JSON object containing at least a ``label``
 185 member. ::
 186
 187     {
 188         "label": "Technology"
 189     }
 190
 191
 192 Relations
 193 ---------
 194
 195 `Relation types <http://tools.ietf.org/html/rfc5988#section-5.3>`_ that are
 196 used in the API:
 197
 198 * ``https://api.gpodder.net/3/relation/tag-podcasts``: podcasts for a given tag
 199
 200 TODO: should they be on domain api.gpodder.net, or just gpodder.net?