doc/api/integration.rst

   1 .. _integration-guide:
   2
   3 Integration Guide
   4 =================
   5
   6 This guide describes how the gpodder.net API can be integrated in podcast
   7 applications. It describes good practice and points out caveats.
   8
   9
  10 General
  11 -------
  12
  13 * The `Mailing List <http://wiki.gpodder.org/wiki/Mailing_List>`_ is the right
  14   place to ask questions
  15
  16 * Consult the :ref:`api-reference` for available functionality.
  17
  18 * Add your client to `the clients list
  19   <http://wiki.gpodder.org/wiki/Web_Services/Clients>`_ when you're ready
  20
  21 * Please use the name *gpodder.net* (all lowercase, .net suffix) to refer to
  22   the webservice. *gPodder* (uppercase P, no suffix) refers to the `client
  23   application <http://gpodder.org/>`_.
  24
  25
  26 Implementation
  27 --------------
  28
  29 * If possible/available use an `existing library
  30   <http://wiki.gpodder.org/wiki/Web_Services/Libraries>`_.
  31
  32 * If you have to implement your own client, please consider releasing it as a
  33   library.
  34
  35 * Try to keep the requests to the API to a sensible limit. There are no hard
  36   limit, please judge for yourself what is necessary in your case. Please ask
  37   on the mailing list if unsure. Your client might get blocked if it
  38   misbehaves.
  39
  40 * Your client should send a useful User-Agent header. We might block clients
  41   with generic/missing User-Agent headers.
  42
  43
  44 Integration
  45 -----------
  46
  47 The following contains useful information for integrating gpodder.net into a
  48 podcast application.
  49
  50
  51 .. _device-integration:
  52
  53 Device
  54 ^^^^^^
  55
  56 Many API endpoints refer to a *device*. A device is an instance of a client
  57 accessing the API. The ID of a device must be unique per user. Therefore
  58 clients should generate a device ID such that it is unique for the user, even
  59 he uses the same application on multiple devices. A common strategy is to
  60 include the applications name and the hostname
  61
  62 A user might use several clients for playing podcasts, which could generate
  63 device Id like the following
  64
  65 * gPodder on his N9 (*gpodder-n9*)
  66 * gPodder on his notebook (*gpodder-netbook*)
  67 * Amarok on his PC (*amarok-mypc*)
  68 * a web based player (*mywebservice-myusername*)
  69
  70 When a previously unknown device Id is used in some API request, a device is
  71 automatically created. Refer to the :ref:`devices-api` on how to provide some
  72 information about the device. Users can manage their devices `online
  73 <https://gpodder.net/devices>`_.
  74
  75
  76 Podcast Directory
  77 ^^^^^^^^^^^^^^^^^
  78
  79 The most basic *passive* integration with gpodder.net is to access some of its
  80 public data. Refer to the :ref:`directory-api` for available endpoints.
  81
  82
  83 Subscription Management
  84 ^^^^^^^^^^^^^^^^^^^^^^^
  85
  86 The most common form of *active* integration is subscription management.
  87 Clients can upload the podcast subscriptions using their device Id and receive
  88 subscription changes (for their device) that were made online. Refer to the
  89 :ref:`subscriptions-api` for additional information.
  90
  91
  92 Episode Actions Synchronization
  93 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  94
  95 Clients can upload and download certain actions (episode downloaded, played,
  96 deleted) to/from gpodder.net. This gives the user a central overview of
  97 where and when he accessed certain podcast episodes, and allows clients to
  98 synchronise states between applications. Refer to the :ref:`events-api` for
  99 further information.