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
  21 Status Codes
  22 ------------
  23
  24 The following status codes can be returned for any API request. Most resources
  25 will, however, define additional status codes.
  26
  27 +----------------------------+-----------------------------------------------+
  28 | Status Code                | Interpretation                                |
  29 +============================+===============================================+
  30 | 200 OK                     | All OK                                        |
  31 +----------------------------+-----------------------------------------------+
  32 | 301 Moved Permanently      | The resource has moved permanently to the     |
  33 |                            | location provided in the Location header.     |
  34 |                            | Subsequent requests should use the new        |
  35 |                            | location directly.                            |
  36 +----------------------------+-----------------------------------------------+
  37 | 303 See Other              | the response to the request is found at the   |
  38 |                            | location provided in the Location header. It  |
  39 |                            | should be retrieved using a GET request       |
  40 +----------------------------+-----------------------------------------------+
  41 | 400 Bad Request            | invalid JSON, invalid types                   |
  42 +----------------------------+-----------------------------------------------+
  43 | 503 Service Unavailable    | The service and/or API are under maintenance  |
  44 +----------------------------+-----------------------------------------------+
  45
  46 * Request not allowed (eg quota, authentication, permissions, etc)
  47
  48
  49 Responses
  50 ---------
  51
  52 All responses are valid JSON (unless otherwise stated).
  53
  54
  55 Error messages
  56 --------------
  57
  58 The response could look like ::
  59
  60     { message: "message", errors: [...] }
  61
  62 Errors could look like this ::
  63
  64     {
  65         resource: "",
  66         field: "",
  67         code: ""
  68     }
  69
  70
  71
  72 Redirects
  73 ---------
  74
  75 permanent (301) vs temporary (302, 307) redirects.
  76
  77
  78 Authentication
  79 --------------
  80
  81 See Authentication API
  82
  83
  84
  85 Rate Limiting
  86 -------------
  87
  88 See usage quotas ::
  89
  90     GET /rate_limit
  91
  92     HTTP/1.1 200 OK
  93     Status: 200 OK
  94     X-RateLimit-Limit: 60
  95     X-RateLimit-Remaining: 56
  96
  97 What counts as request? conditional requests?
  98
  99
 100
 101 Conditional Requests
 102 --------------------
 103
 104 Some responses return ``Last-Modified`` and ``ETag`` headers. Clients SHOULD
 105 use the values of these headers to make subsequent requests to those resources
 106 using the ``If-Modified-Since`` and ``If-None-Match`` headers, respectively. If
 107 the resource has not changed, the server will return a ``304 Not Modified``.
 108 Making a conditional request and receiving a 304 response does not count
 109 against the rate limit.
 110
 111
 112 Formats
 113 -------
 114
 115 All data is exchanged as `JSON <http://tools.ietf.org/html/rfc4627>`_. All
 116 resources are represented as JSON objects, and requests are expected as also
 117 expected to contain JSON objects.
 118
 119
 120 JSONP Callbacks
 121 ^^^^^^^^^^^^^^^
 122
 123 You can pass a ``?callback=<function-name>`` parameter to any GET call to have
 124 the results wrapped in a JSON function. This is typically used when browsers
 125 want to embed content received from the API in web pages by getting around
 126 cross domain issues. The response includes the same data output as the regular
 127 API, plus the relevant HTTP Header information.