From gPodderWiki
(Redirected from Web Services/API)
Jump to: navigation, search

This is the specification of Version 2 of the public API for the gpodder.net Web Services.

Please consult the Integration Guide before integrating the gpodder.net API in your application.

There are two different APIs for different target audiences:

  • The Simple API targets developers who want to write quick integration into their existing applications
  • The Advanced API targets developers who want tight integration into their applications (with more features)

The API is versioned so that changes in the major version number indicate backwards incompatible changes. All other changes preserve backwards compatibility. See Web Services/API History for a list of changes. The current version is 2.11. This versioning scheme has been introduced in [1].

Protocol: The API can be accessed via http and https. https is preferable from a security / privacy point of view and should be used by all clients. gpodder.net also seems to be blocked in China via plain http.

All endpoints send the Access-Control-Allow-Origin: * header which allows web application to access the API.

Overview[edit]

Function Description Formats Requires Auth
Directory
Podcast Toplist get the most-subscribed podcasts OPML, JSON, JSONP, TXT, XML no
Podcast Search search for podcasts OPML, JSON, JSONP, TXT, XML no
Get Top Tags get the top tags of the podcast directory JSON no
Get Podcasts for Tag get top podcasts for a tag in the podcast directory JSON no
Get Podcast Data get data for a feed URL JSON no
Get Episode Data get data for a media URL JSON no
Suggestions
Podcast Suggestions get suggestion podcasts based on the user's subscriptions OPML, JSON, JSONP, TXT, XML yes
Subscriptions
Upload Upload the subscriptions of one client OPML, JSON, JSONP, TXT, XML yes
Get Get the subscriptions of one client OPML, JSON, JSONP, TXT, XML yes
Get All Get the (combined) subscriptions of all of the user's devices JSON yes
Upload Changes Upload changes to the subscriptions of one client (added 1 subscription, removed 2 subscriptions) JSON yes
Get Changes Get changes to the subscriptions of one client since a specific timestamp (added 1 subscriptions, removed 2 subscriptions) JSON yes
Episode Actions
Upload Upload episode-related events (eg downloaded, played) JSON yes
Get Get episode-related events since a specific timestamp (eg downloaded, played) JSON yes
Devices
List List of of the user's devices (clients) JSON yes
Configure Set the name and type of the user's devices (clients) JSON yes
Get Updates get aggregated updates for a user's device (new episodes, episode actions, etc) JSON yes
Settings
Save store arbitrary JSON values per user account, device, podcast or episode JSON yes
Get get arbitrary JSON values per user account, device, podcast or episode JSON yes
Favorites
Get Favorite Episodes get all of the user's favorited episode JSON yes
Authentication
Login login a user JSON yes
Logout logout JSON yes
Device Sync
Status get information about synchronized devices JSON yes
Start / Stop synchronize devices or stop synchronization JSON yes
Podcast Lists
Create create a list of related podcasts for sharing JSON yes
List get a list of all podcast lists of a user JSON yes
Get get a podcast list of a user OPML, JSON, JSONP, TXT, XML no
Update update a podcast list OPML, JSON, JSONP, TXT, XML yes
Delete delete a podcast list OPML, JSON, JSONP, TXT, XML yes

Implementations[edit]


API Parametrization[edit]

  • Since 2.7

Clients should retrieve and process clientconfig.json before making requests to the webservice. If a client can not process the configuration, it can assume the default configuration given in the clientconfig.json documentation.

Devices[edit]

Devices are used throughout the API to identify a device / a client application. A device ID can be any string matching the regular expression "[\w.-]+". The client application MUST generate a string to be used as its device ID, and SHOULD ensure that it is unique within the user account. A good approach is to combine the application name and the name of the host it is running on.

If two applications share a device ID, this might cause subscriptions to be overwritten on the server side. While it is possible to retrieve a list of devices and their IDs from the server, this SHOULD NOT be used to let a user select an existing device ID.


Formats[edit]

Most of the 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

[
 {
   "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

<podcasts>
 <podcast>
  <title>Linux Outlaws</title>
  <url>http://feeds.feedburner.com/linuxoutlaws</url>
  <website>http://sixgun.org</website>
  <mygpo_link>http://gpodder.net/podcast/11092</mygpo_link>
  <description>The hardest-hitting Linux podcast around</description>
  <subscribers>1954</subscribers>
  <subscribers_last_week>1943</subscribers_last_week>
  <logo_url>http://sixgun.org/files/linuxoutlaws.jpg</logo_url>
  <scaled_logo_url>http://gpodder.net/logo/64/fa9fd87a4f9e488096e52839450afe0b120684b4.jpg</scaled_logo_url>
 </podcast>
</podcasts>


API Variants[edit]

Simple API[edit]

The Simple API provides a way to upload and download subscription lists in bulk. This allows developers of podcast-related applications to quickly integrate support for the web service, as the only

  • Synchronization of episode status fields is not supported
  • This API uses more bandwith than the advanced API
  • The client can be stateless
  • The client can be low-powered - subscribe/unsubscribe events are calculated on the server-side


Advanced API[edit]

The Advanced API provides more flexibility and enhanced functionality for applications that want a tighter integration with the web service. A reference implementation will be provided as part of the gPodder source code (and gPodder will make use of that reference implementation).

  • The client has to persist the synchronization state locally
  • Only changes to subscriptions are uploaded and downloaded
  • Synchronization of episode status fields is supported in this API
  • Only JSON is used as the data format to ease development