From 585d4aede7687874ffec55f3176984d933174f3a Mon Sep 17 00:00:00 2001 From: =?utf8?q?Stefan=20K=C3=B6gl?= Date: Wed, 1 May 2013 10:40:13 +0200 Subject: [PATCH] update general api docs, merge with formats doc --- doc/api/reference/formats.rst | 51 ----------------------- doc/api/reference/general.rst | 94 ++++++++++++++++++++++++++++++++++++++++++- doc/api/reference/index.rst | 1 - 3 files changed, 93 insertions(+), 53 deletions(-) delete mode 100644 doc/api/reference/formats.rst diff --git a/doc/api/reference/formats.rst b/doc/api/reference/formats.rst deleted file mode 100644 index 22a7487e..00000000 --- a/doc/api/reference/formats.rst +++ /dev/null @@ -1,51 +0,0 @@ -Formats -======= - -Some resources are offered in several different formats - -* OPML -* JSON -* JSONP with an option function name that wraps the result (since 2.8) -* plain text with one URL per line -* XML a custom XML format (see example, since 2.9) - -JSON ----- - -JSON:: - - [ - { - "website": "http://sixgun.org", - "description": "The hardest-hitting Linux podcast around", - "title": "Linux Outlaws", - "url": "http://feeds.feedburner.com/linuxoutlaws", - "position_last_week": 1, - "subscribers_last_week": 1943, - "subscribers": 1954, - "mygpo_link": "http://gpodder.net/podcast/11092", - "logo_url": "http://sixgun.org/files/linuxoutlaws.jpg", - "scaled_logo_url": "http://gpodder.net/logo/64/fa9fd87a4f9e488096e52839450afe0b120684b4.jpg" - }, - # more podcasts here - ] - -XML ---- - -.. code-block:: xml - - - - Linux Outlaws - http://feeds.feedburner.com/linuxoutlaws - http://sixgun.org - http://gpodder.net/podcast/11092 - The hardest-hitting Linux podcast around - 1954 - 1943 - http://sixgun.org/files/linuxoutlaws.jpg - http://gpodder.net/logo/64/fa9fd87a4f9e488096e52839450afe0b120684b4.jpg - - - diff --git a/doc/api/reference/general.rst b/doc/api/reference/general.rst index fc1836f6..590f1bce 100644 --- a/doc/api/reference/general.rst +++ b/doc/api/reference/general.rst @@ -8,6 +8,11 @@ seems to be blocked in China via plain http. All endpoints are offered at https://api.gpodder.net/3/. +* Request and Response Formats: JSON +* JSONP also available +* Date format: ISO 8601 / `RFC 3339 `_ + ``YYYY-MM-DDTHH:MM:SSZ`` + Podcast is identified by its feed URL, episode is identified by its media URL. TODO: see http://developer.github.com/v3/ for relevant information! @@ -16,13 +21,25 @@ TODO: see http://developer.github.com/v3/ for relevant information! Status Codes ------------ -The API uses the following status codes +The following status codes can be returned for any API request. Most resources +will, however, define additional status codes. +----------------------------+-----------------------------------------------+ | Status Code | Interpretation | +============================+===============================================+ | 200 OK | All OK | +----------------------------+-----------------------------------------------+ +| 301 Moved Permanently | The resource has moved permanently to the | +| | location provided in the Location header. | +| | Subsequent requests should use the new | +| | location directly. | ++----------------------------+-----------------------------------------------+ +| 303 See Other | the response to the request is found at the | +| | location provided in the Location header. It | +| | should be retrieved using a GET request | ++----------------------------+-----------------------------------------------+ +| 400 Bad Request | invalid JSON, invalid types | ++----------------------------+-----------------------------------------------+ | 503 Service Unavailable | The service and/or API are under maintenance | +----------------------------+-----------------------------------------------+ @@ -33,3 +50,78 @@ Responses --------- All responses are valid JSON (unless otherwise stated). + + +Error messages +-------------- + +The response could look like :: + + { message: "message", errors: [...] } + +Errors could look like this :: + + { + resource: "", + field: "", + code: "" + } + + + +Redirects +--------- + +permanent (301) vs temporary (302, 307) redirects. + + +Authentication +-------------- + +See Authentication API + + + +Rate Limiting +------------- + +See usage quotas :: + + GET /rate_limit + + HTTP/1.1 200 OK + Status: 200 OK + X-RateLimit-Limit: 60 + X-RateLimit-Remaining: 56 + +What counts as request? conditional requests? + + + +Conditional Requests +-------------------- + +Some responses return ``Last-Modified`` and ``ETag`` headers. Clients SHOULD +use the values of these headers to make subsequent requests to those resources +using the ``If-Modified-Since`` and ``If-None-Match`` headers, respectively. If +the resource has not changed, the server will return a ``304 Not Modified``. +Making a conditional request and receiving a 304 response does not count +against the rate limit. + + +Formats +------- + +All data is exchanged as `JSON `_. All +resources are represented as JSON objects, and requests are expected as also +expected to contain JSON objects. + + +JSONP Callbacks +^^^^^^^^^^^^^^^ + +You can pass a ``?callback=`` parameter to any GET call to have +the results wrapped in a JSON function. This is typically used when browsers +want to embed content received from the API in web pages by getting around +cross domain issues. The response includes the same data output as the regular +API, plus the relevant HTTP Header information. diff --git a/doc/api/reference/index.rst b/doc/api/reference/index.rst index 04c17416..32a2805a 100644 --- a/doc/api/reference/index.rst +++ b/doc/api/reference/index.rst @@ -21,7 +21,6 @@ integrating gpodder.net into podcasting applications. :maxdepth: 3 general - formats registration auth user -- 2.11.4.GIT