api-docs/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
  52 ^^^^^^
  53
  54 Many API endpoints refer to a *device*. A device is an instance of a client
  55 accessing the API. The ID of a device must be unique per user. Therefore
  56 clients should generate a device ID such that it is unique for the user, even
  57 he uses the same application on multiple devices. A common strategy is to
  58 include the applications name and the hostname
  59
  60 A user might use several clients for playing podcasts, which could generate
  61 device Id like the following
  62
  63 * gPodder on his N9 (*gpodder-n9*)
  64 * gPodder on his notebook (*gpodder-netbook*)
  65 * Amarok on his PC (*amarok-mypc*)
  66 * a web based player (*mywebservice-myusername*)
  67
  68 When a previously unknown device Id is used in some API request, a device is
  69 automatically created. Refer to the :ref:`devices-api` on how to provide some
  70 information about the device. Users can manage their devices `online
  71 <https://gpodder.net/devices>`_.
  72
  73
  74 Podcast Directory
  75 ^^^^^^^^^^^^^^^^^
  76
  77 The most basic *passive* integration with gpodder.net is to access some of its
  78 public data. Refer to the :ref:`directory-api` for available endpoints.
  79
  80
  81 Subscription Management
  82 ^^^^^^^^^^^^^^^^^^^^^^^
  83
  84 The most common form of *active* integration is subscription management.
  85 Clients can upload the podcast subscriptions using their device Id and receive
  86 subscription changes (for their device) that were made online. Refer to the
  87 :ref:`subscriptions-api` for additional information.
  88
  89
  90 Episode Actions Synchronization
  91 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  92
  93 Clients can upload and download certain actions (episode downloaded, played,
  94 deleted) to/from gpodder.net. This gives the user a central overview of
  95 where and when he accessed certain podcast episodes, and allows clients to
  96 synchronise states between applications. Refer to the :ref:`events-api` for
  97 further information.