Web Services/API 3 (Draft)

From gPodderWiki

This is a draft for version 3 of the public API for the gpodder.net Web Services.

Contents 1 Proposed Changes to API 2 2 Additional Ideas 3 API Parametrization 4 Subscriptions 4.1 Downloading Subscription Lists 4.2 Uploading Subscription Lists 4.3 Uploading Subscription Changes 4.4 Retrieving Subscription Changes 5 Directory 5.1 Podcast Toplist 5.2 Podcast Suggestions 5.3 Podcast Search 6 Retrieving Top Tags 6.1 Retrieving Podcasts for a Tag 6.2 Retrieving Podcast Data 6.3 Retrieving Episode Data 7 Episode States 7.1 Uploading Episode Actions 7.2 Retrieving Episode Actions 7.3 Listing Favorite Episodes 8 Device Management 8.1 Changing Device Settings 8.2 Listing Devices 8.3 Retrieving Updates for a Device 9 Settings 9.1 Known Settings 9.2 Saving a Setting 9.3 Retrieving Settings

[edit] Proposed Changes to API 2

• The classification between Simple and Advanced API is dropped
• A separate domain name for API requests will be used (something like api.gpodder.net, see #API Parametrization)
• The /api/ prefix has been dropped (in favor of a API domain name) and a version prefix (/3/) has been added for all endpoints
• Device-Data and Settings are updated with PUT instead of POST (because they overwrite existing data)

[edit] Additional Ideas

• Use authentication protocol (OAuth2?)

[edit] API Parametrization

• 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.

[edit] Subscriptions

[edit] Downloading Subscription Lists

• Request: GET /3/subscriptions/{username}/{device_id}.opml
• Request: GET /3/subscriptions/{username}/{device_id}.json
• Request: GET /3/subscriptions/{username}/{device_id}.jsonp?jsonp={function-name} (since 2.8)
• Request: GET /3/subscriptions/{username}/{device_id}.txt
• Requires HTTP authentication
• Since 1.0

Get a list of subscribed podcasts for the given user. The first variant returns the content as OPML feed, the second variant as list of feed URLs in JSON format. The third variant returns the list of URLs (one per line) as simple plaintext.

• Example: GET /3/subscriptions/bob/asdf.opml (Download bob's list for device ID asdf as OPML)

In case of errors, the following HTTP status codes are used:

• 401 Invalid user
• 404 Invalid device ID
• 400 Invalid format (e.g. broken OPML)

[edit] Uploading Subscription Lists

• Request: PUT /3/subscriptions/{username}/{device_id}.opml
• Request: PUT /3/subscriptions/{username}/{device_id}.json
• Request: PUT /3/subscriptions/{username}/{device_id}.txt
• Requires HTTP authentication
• Since 1.0

Upload the current subscription list of the given user to the server. The data should be provided either in OPML, JSON or plaintext (one URL per line) format, and should be uploaded just like a normal PUT request (i.e. in the body of the request).

For successful updates, the implementation always returns the status code 200 and the empty string (i.e. an empty HTTP body) as a result, any other string should be interpreted by the client as an (undefined) error.

Defined errors are as follows (in this case, the body that is received from the server might be a user-friendy description of the error):

• 401 Invalid user
• 400 Invalid format (cannot parse OPML or JSON)

In case the device does not exist for the given user, it is automatically created. If clients want to determine if a device exists, you have to to a GET request on the same URL first and check for a the 404 status code (see above).

• Example: PUT /3/subscriptions/john/e9c4ea4ae004efac40.txt (Upload john's list for that device as text file)

[edit] Uploading Subscription Changes

• Request: POST /3/subscriptions/{username}/{device_id}.json
• Requires HTTP authentication
• Since 2.0

Update the subscription list for a given device. Only deltas are supported here. Timestamps are not supported, and are issued by the server.

Example JSON upload data:

 {"add": ["http://example.com/feed.rss", "http://example.org/podcast.php"],
  "remove": ["http://example.net/foo.xml"]}

Please note that adding and removing the same Feed in one request is not possible. Status code 400 Bad Request will be returned for such requests.

In positive responses the server returns a timestamp/ID that can be used for requesting changes since this upload in a subsequent API call (see below):

 {"timestamp": 12345, "update_urls": []}

In addition, the server MUST send any URLs that have been rewritten (sanitized, see bug:747) as a list of tuples with the key "update_urls". The client SHOULD parse this list and update the local subscription list accordingly (the server only sanitizes the URL, so the semantic "content" should stay the same and therefore the client can simply update the URL value locally and use it for future updates. An example result with update_urls:

 {"timestamp": 1337,
  "update_urls": [
   ["http://feeds2.feedburner.com/LinuxOutlaws?format=xml",
    "http://feeds.feedburner.com/LinuxOutlaws"],
   ["http://example.org/podcast.rss ",
    "http://example.org/podcast.rss"]]}

URLs that are not allowed (currently all URLs that don't start with either http or https) are rewritten to the empty string and are ignored by the Webservice.

[edit] Retrieving Subscription Changes

• Request: GET /3/subscriptions/{username}/{device_id}.json?since={timestamp}
• Requires HTTP authentication
• Since 2.0

This API call retrieves only the changes since the last upload (the last upload is determined by the "since" parameter, which usually is taken from the return value of a previous update call). The response format is the same as the upload format, i.e. JSON: A dictionary with two keys "add" and "remove" where the value for each key is a list of URLs that should be added or removed. There is one additional key ("timestamp") that is provided by the server that will tell the client the next value for the "since" parameter in case the client wants to issue another GET request in the future without uploading data.

In case nothing has changed, the server returns something like the following JSON content (in this case, the client SHOULD store the timestamp and use it for future requests):

 {"add": [], "remove": [], "timestamp": 12347}

[edit] Directory

[edit] Podcast Toplist

• Request: GET /3/toplist/{number}.opml
• Request: GET /3/toplist/{number}.json
• Request: GET /3/toplist/{number}.jsonp?jsonp={function-name} (since 2.8)
• Request: GET /3/toplist/{number}.txt
• Does not require authentication (public content)
• Since 1.0

The number field might be any value in the range 1..100 (inclusive both boundaries). An example request looks like:

• GET /3/toplist/50.json - Get the top 50 list in JSON format

Download a list of podcasts, sorted in descending order (more popular podcasts first) in different formats. The OPML and TXT formats do not add any information about the (absolute and relative) popularity for each podcast, only the ordering can be considered. The JSON format includes a more detailed list, usable for clients that want to display a detailed toplist or post-process the toplist:

[
 {
   "website": "http://linuxoutlaws.com/podcast", 
   "description": "Open source talk with a serious attitude", 
   "title": "Linux Outlaws", 
   "url": "http://feeds.feedburner.com/linuxoutlaws", 
   "position_last_week": 0, 
   "subscribers_last_week": 1736, 
   "subscribers": 1736, 
   "mygpo_link": "http://www.gpodder.net/podcast/11092", 
   "logo_url": "http://linuxoutlaws.com/files/albumart-itunes.jpg"
 }, 
 {
   "website": "http://syndication.mediafly.com/redirect/show/d581e9b773784df7a56f37e1138c037c", 
   "description": "We're not talking dentistry here; FLOSS all about Free Libre Open Source Software. Join hosts Randal Schwartz and Leo Laporte every Saturday as they talk with the most interesting and important people in the Open Source and Free Software community.", 
   "title": "FLOSS Weekly Video (large)", 
   "url": "http://feeds.twit.tv/floss_video_large", 
   "position_last_week": 0, 
   "subscribers_last_week": 50, 
   "subscribers": 50, 
   "mygpo_link": "http://www.gpodder.net/podcast/31991", 
   "logo_url": "http://static.mediafly.com/publisher/images/06cecab60c784f9d9866f5dcb73227c3/icon-150x150.png"
 }]

All shown keys must be provided by the server. The description field may be set to the empty string in case a description is not available. The title field may be set to the URL in case a title is not available. The subscribers_last_week field may be set to zero if no data is available. The client can use the subscribers_last_week counts to re-sort the list and get a ranking for the last week. With this information, a relative "position movement" can also be calculated if the developer of the client decides to do so.

[edit] Podcast Suggestions

• Request: GET /3/suggestions/{number}.opml
• Request: GET /3/suggestions/{number}.json
• Request: GET /3/suggestions/{number}.json?jsonp={function-name} (since 2.8)
• Request: GET /3/suggestions/{number}.txt
• Requires HTTP authentication
• Since 1.0

The number field might be any value in the range 1..100 (inclusive both boundaries). An example request looks like:

• GET /3/suggestions/10.opml - Get 10 suggestions in OPML format

Download a list of podcasts that the user has not yet subscribed to (by checking all server-side subscription lists) and that might be interesting to the user based on existing subscriptions (again on all server-side subscription lists).

The TXT format is a simple URL list (one URL per line), and the OPML file is a "standard" OPML feed. The JSON format looks as follows:

[
  {
   "website": "http://www.linuxgeekdom.com", 
   "mygpo_link": "http://gpodder.net/podcast/64439", 
   "description": "Linux Geekdom", 
   "subscribers": 0, 
   "title": "Linux Geekdom", 
   "url": "http://www.linuxgeekdom.com/rssmp3.xml", 
   "subscribers_last_week": 0, 
   "logo_url": null
 }, 
 {
   "website": "http://goinglinux.com", 
   "mygpo_link": "http://gpodder.net/podcast/11171", 
   "description": "Going Linux", 
   "subscribers": 571, 
   "title": "Going Linux", 
   "url": "http://goinglinux.com/mp3podcast.xml", 
   "subscribers_last_week": 571, 
   "logo_url": "http://goinglinux.com/images/GoingLinux80.png"
 }]

The server does not specify the "relevance" for the podcast suggestion, and the client application SHOULD filter out any podcasts that are already added to the client application but that the server does not know about yet (although this is just a suggestion for a good client-side UX).

[edit] Podcast Search

• Request: GET /3/search.opml?q={query}
• Request: GET /3/search.json?q={query}
• Request: GET /3/search.jsonp?q={query}&jsonp={function-name} (since 2.8)
• Request: GET /3/search.txt?q={query}
• Does not require authentication (public content)
• Since 2.0

Carries out a service-wide search for podcasts that match the given query. Returns a list of podcasts.

The format of the search results is the same as for podcast suggestions. See there for the exact format.

[edit] Retrieving Top Tags

• Request: GET /3/tags/{count}.json
• Does not require authentication
• Since 2.2

Returns a list of the count most used tags.

[
  {"tag": "Technology",
   "usage": 530 }.
  {"tag": "Society & Culture".
   "usage": 420 },
  {"tag": "Arts".
   "usage": 400},
  {"tag": "News & Politics".
   "usage": 320}
]

[edit] Retrieving Podcasts for a Tag

• Request: GET /3/tag/{tag}/{count}.json
• Does not require authentication
• Since 2.2

Returns the count most-subscribed podcasts that are tagged with tag.

[
 {"url": "http://leo.am/podcasts/floss",
  "title": "FLOSS Weekly",
  "description": "Each Thursday we talk about Free Libre and Open Source Software with the people who are writing it. Part of the TWiT Netcast Network.",
  "subscribers": 1138,
  "logo_url: "http://leoville.tv/podcasts/coverart/floss144audio.jpg",
  "website": "http://twit.tv/",
  "mygpo_link": "http://gpodder.net/podcast/12925"},

 {"url": "http://leo.am/podcasts/twit",
  "title": "this WEEK in TECH - MP3 Edition",
  "description": "Your first podcast of the week is the last word in tech. [...]",
  "subscribers": 895,
  "logo_url": "http://leoville.tv/podcasts/coverart/twit144audio.jpg",
  "website": "http://thisweekintech.com/",
  "mygpo_link": "http://thisweekintech.com/"}
]

[edit] Retrieving Podcast Data

• Request: GET: /3/data/podcast.json?url={url}
• No authentication required
• Since 2.2

Returns information for the podcast with the given URL or 404 if there is no podcast with this URL.

{
 "website": "http://coverville.com", 
 "mygpo_link": "http://www.gpodder.net/podcast/16124", 
 "description": "The best cover songs, delivered to your ears two to three times a week!", 
 "subscribers": 19, 
 "title": "Coverville", 
 "url": "http://feeds.feedburner.com/coverville", 
 "subscribers_last_week": 19, 
 "logo_url": "http://www.coverville.com/art/coverville_iTunes300.jpg"
}

[edit] Retrieving Episode Data

• Request: GET /3/data/episode.json?podcast={podcast-url}&url={episode-url}
• Does not require authentication
• Since 2.2 (added released in 2.6)

Returns information for the episode with the given {episode-url} that belongs to the podcast with the {podcast-url}

{
 "title": "TWiT 245: No Hitler For You",
 "url": "http://www.podtrac.com/pts/redirect.mp3/aolradio.podcast.aol.com/twit/twit0245.mp3",
 "podcast_title": "this WEEK in TECH - MP3 Edition",
 "podcast_url": "http://leo.am/podcasts/twit", 
 "description": "[...]",
 "website": "http://www.podtrac.com/pts/redirect.mp3/aolradio.podcast.aol.com/twit/twit0245.mp3", 
 "released": "2010-12-25T00:30:00",
 "mygpo_link": "http://gpodder.net/episode/1046492"
}

[edit] Episode States

[edit] Uploading Episode Actions

• Request: POST /3/episodes/{username}.json
• Requires HTTP authentication
• Since 2.0

Upload changed episode actions. As actions are saved on a per-user basis (not per-device), the API endpoint is the same for every device. For logging purposes, the client can send the device ID to the server, so it appears in the episode action log on the website.

Example JSON upload data:

 [{"podcast": "http://example.com/feed.rss",
   "episode": "http://example.com/files/s01e20.mp3",
   "device": "gpodder_abcdef123",
   "action": "download",
   "timestamp": "2009-12-12T09:00:00"},
  {"podcast": "http://example.org/podcast.php",
   "episode": "http://ftp.example.org/foo.ogg",
   "action": "play",
   "started": 15,
   "position": 120,
   "total":  500}]

Possible keys:

• podcast (required)
  • The URL to the podcast feed the episode belongs to
• episode (required)
  • The download URL/GUID of the episode
• device (optional)
  • The device ID on which the action has taken place
• action (required)
  • One of: download, play, delete, new
• timestamp (optional)
  • An optional timestamp when the action took place, in ISO 8601 format - The timestamp MUST be in the UTC time zone
• started (optional)
  • Only valid for "play": the position (in seconds) at which the client started playback (requires "position" to be set)
• position (optional)
  • Only valid for "play": the position (in seconds) at which the client stopped playback
• total (optional)
  • Only valid for "play": the total length of the file in seconds (requires "position" to be set)

The return value is a JSON dictionary containing the timestamp:

   {"timestamp": 12345,
    "update_urls": [] }

In addition, the server MUST send any URLs that have been rewritten (sanitized, see bug:747 and bug:862) as a list of tuples with the key "update_urls". The client SHOULD parse this list and update the local subscription and episode list accordingly (the server only sanitizes the URL, so the semantic "content" should stay the same and therefore the client can simply update the URL value locally and use it for future updates. An example result with update_urls:

 {"timestamp": 1337,
  "update_urls": [
   ["http://feeds2.feedburner.com/LinuxOutlaws?format=xml",
    "http://feeds.feedburner.com/LinuxOutlaws"],
   ["http://example.org/episode.mp3 ",
    "http://example.org/episode.mp3"]]}

URLs that are not allowed (currently all URLs that contain non-ASCII characters or don't start with either http or https) are rewritten to the empty string and are ignored by the Webservice.

[edit] Retrieving Episode Actions

• Request: GET /3/episodes/{username}.json
• Request: GET /3/episodes/{username}.json?podcast={url}
• Request: GET /3/episodes/{username}.json?device={device-id}
• Request: GET /3/episodes/{username}.json?since={timestamp}
• Request: GET /3/episodes/{username}.json?podcast={url}&since={timestamp}
• Request: GET /3/episodes/{username}.json?device={device-id}&since={timestamp}
• Request: GET /3/episodes/{username}.json?podcast={url}&aggregated=true
• Requires HTTP authentication
• Since 2.0 (aggregated=true added in 2.1)

Download changed episode actions. The result is a list of all episode actions that were uploaded since the given timestamp (regardless of the action timestamp itself). The timestamp SHOULD be the value returned by the previous episode retrieve request. The first three variants (without the "since" parameter) downloads ALL episode actions for the given user. Please note that this could be a potentially long list of episode actions, so clients SHOULD prefer the "since" variants whenever possible (e.g. when uploads have been taken place before).

When adding the aggregated=true parameter, the server only sends the latest action for each episode. This method can be used to determine the current state of some episode. The parameter can be added to each combination of the other parameters.

The format of the action list is the same as with the action upload request, but the format is a bit different so that the server can send the new timestamp (that the client SHOULD save and use for subsequent requests):

   {"actions": (list of episode actions here - see above for details),
    "timestamp": 12345}

There are two additional variants that take either a podcast URL or a device ID and returns only episode actions related to the given podcast or device. In the case of the device ID, all podcasts to which the device is currently subscribe to, are combined, and episode actions for these are added.

Client implementation notes: A client can make use of the device variant of this request when it is assigned a single device id. When adding a podcast to the client (without synching the subscription list straight away), the variant with the podcast URL can be used. The first variant (no parameters at all) can be used as a kind of "burst" download of all episode actions, but should be used as little as possible (e.g. after a re-install, although even then, the device-id parameter could be more useful).

[edit] Listing Favorite Episodes

• Request GET /3/favorites/<username>.json
• Requires Authentication
• Since 2.4 (added released in 2.6)

The response is a list of all favorite episodes, as they can be seen on http://gpodder.net/favorites/

[
   {
     "title": "TWiT 245: No Hitler For You",
     "url": "http://www.podtrac.com/pts/redirect.mp3/aolradio.podcast.aol.com/twit/twit0245.mp3",
     "podcast_title": "this WEEK in TECH - MP3 Edition",
     "podcast_url": "http://leo.am/podcasts/twit", 
     "description": "[...]",
     "website": "http://www.podtrac.com/pts/redirect.mp3/aolradio.podcast.aol.com/twit/twit0245.mp3", 
     "released": "2010-12-25T00:30:00",
     "mygpo_link": "http://gpodder.net/episode/1046492"
    }
]

[edit] Device Management

[edit] Changing Device Settings

• Request: PUT /3/devices/{username}/{device-id}.json
• Requires HTTP authentication
• Since 2.0

Set a new name for the device ID. The device ID is normally generated by the client application, but for viewing the device on the web and for managing subscriptions, it's easier to provide a "human-readable" name. The client application should do this using this API call. It can also provide the type of device, so that a special icon can be shown in the web UI. Only the keys that are supplied will be updated.

 {"caption": "gPodder on my Lappy", "type": "laptop"}

Possible keys:

• caption
  • The new label for the device
• type
  • The type of the device. (Possible values: desktop, laptop, mobile, server, other)

[edit] Listing Devices

• Request: GET /3/devices/{username}.json
• Requires HTTP authentication
• Since 2.0

Returns the list of devices that belong to a user. This can be used by the client to let the user select a device from which to retrieve subscriptions, etc..

 [{"id": "abcdef",
   "caption": "gPodder on my Lappy",
   "type": "laptop",
   "subscriptions": 27},
  {"id": "09jc23caf",
   "caption": "",
   "type": "other",
   "subscriptions": 30},
  {"id": "phone-au90f923023.203f9j23f",
   "caption": "My Phone",
   "type": "mobile",
   "subscriptions": 5}]

[edit] Retrieving Updates for a Device

• Request GET /3/updates/<username>/<device>.json?since=<timestamp>
• Requires Authentication
• Since 2.3

With this query you can retrieve episode and subscription updates for the given device.

The response will have the following form and will contain

• a list of subscriptions to be added, with URL, title and descriptions
• a list of URLs to be unsubscribed
• a list of updated episodes
• the current timestamp; for retrieving changes since the last query

 {"add":     [
    {
       "title": "PaulDotCom Security Weekly", 
       "url": "http://pauldotcom.com/podcast/psw.xml", 
       "description": "PaulDotCom Security Weekly Podcast with Paul, Larry, Mick, Carlos, and special guests!", 
       "subscribers": 93, 
       "logo_url": "http://pauldotcom.com/images/psw-logo-sm.png"
       "website": "http://pauldotcom.com/", 
       "mygpo_link": "http://gpodder.net/podcast/11194", 
    }
  ],

  "remove":  ["<URL3>"],

  "updates": [
    {
      "title": "TWiT 245: No Hitler For You",
      "url": "http://www.podtrac.com/pts/redirect.mp3/aolradio.podcast.aol.com/twit/twit0245.mp3",
      "podcast_title": "this WEEK in TECH - MP3 Edition",
      "podcast_url": "http://leo.am/podcasts/twit", 
      "description": "[...]",
      "website": "http://www.podtrac.com/pts/redirect.mp3/aolradio.podcast.aol.com/twit/twit0245.mp3", 
      "mygpo_link": "http://gpodder.net/episode/1046492"
      "released":   """2009-12-12T09:00:00"
      "status":        "(new|play|download|delete)"
     }
    ],

   "timestamp":   <timestamp>
  }

[edit] Settings

Clients can store settings and retrieve settings as key-value-pairs, which are attached to either account, device, podcast or episode.

Keys are the names of the settings and are supposed to be strings. Values can be any valid JSON objects.

[edit] Known Settings

Although settings are primarily used to exchange settings between clients, some of them also trigger some behavior on the website.

• Account
  • public_profile: when set to False, sets all podcasts to private (as on http://gpodder.net/account/privacy, currently deactivated via API)

• Episode
  • is_favorite: flags the episode as favorite (can be done on any episode-page)

• Podcast
  • public_subscription: when set to False, sets the subscription to this podcast to private (as on http://gpodder.net/account/privacy or any podcast-page, currently deactivated via API)

[edit] Saving a Setting

• Request: PUT /3/settings/<username>/(account|device|podcast|episode).json?<scope-specification>

• scope, together with the scope-specification specifies to which object a setting is attached
  • podcast: Parameter: podcast=<feed-url>
  • account: no parameters needed
  • device: Parameter: device=<device-id>
  • episode: Parameters: podcast=<feed-url>&episode=<media-url>
• Requires Authentication
• Since 2.4

Post-Data

{
 "set": {"setting1": "value1", "setting2": "value2"},
 "remove": ["setting3", "setting4"] 
} 

set is a dictionary of settings to add or update; remove is a list of keys that shall be removed from the scope.

The response contains all settings that the scope has after the update has been carried out.

{
 "setting1": "value1",
 "setting2": "value"
}

[edit] Retrieving Settings

• Request GET /3/settings/<username>/(account|device|podcast|episode).json?<scope-specification>
• Scope and specification as above
• Requires Authentication
• Since 2.4

The response contains all settings that the scope currently has

{"setting1": "value1", "setting2": "value2"}