doc/api/api3.rst

   1 .. _api3:
   2
   3
   4 API 3 (Draft)
   5 =============
   6
   7 This is *a draft* for version 3 of the public API of gpodder.net.
   8
   9 Client Access
  10 -------------
  11
  12 * Require client keys to identify clients, get a communication channel
  13   to developers
  14 * Clients must send a valid User-Agent string
  15 * API usage free for open source clients
  16 * Quota for non-open clients -- higher quota if more features are
  17   implemented; paid quota increase
  18
  19 Proposed Changes to API 2
  20 -------------------------
  21 * The classification between Simple and Advanced API is dropped
  22 * A separate domain name for API requests will be used (something like
  23   api.gpodder.net, see :ref:`api-parametrization`
  24 * The ``/api/`` prefix has been dropped (in favor of a API domain name) and a
  25   version prefix (``/3/``) has been added for all endpoints
  26 * Device-Data and Settings are updated with PUT instead of POST (because they
  27   overwrite existing data)
  28 * Things to consider:
  29   `Evolving HTTP APIs <http://www.mnot.net/blog/2012/12/04/api-evolution>`_
  30
  31 Additional Ideas
  32 ----------------
  33
  34 * Use authentication protocol `OAuth2
  35   <https://tools.ietf.org/html/draft-ietf-oauth-v2-18>`_
  36
  37 Open Questions
  38 --------------
  39 * What's the best way of documenting a REST API?
  40   http://stackoverflow.com/questions/898321/standard-methods-for-documenting-a-restful-api
  41   http://answers.oreilly.com/topic/1390-how-to-document-restful-web-services/
  42 * Specify deprecation guideline + timeline for when the old API will stop
  43   functioning
  44