User:LesOrchard/BandwagonAPI: Difference between revisions

Revision as of 19:33, 4 February 2009

Bandwagon API

Implementation Notes

This API uses the REST pattern of including resource URLs in responses, rather than database IDs or other identifiers. This allows the server to control its own namespace, so please use the URLs found in href attributes to access the API, rather than constructing them on the client side from templates.

For GET requests, be sure to retain the value of the Last-Modified header in responses and include it as If-Modified-Since in requests. This enables conditional GET and may result in 304 Not Modified responses that indicate the resource has not changed since the last fetch. This will save in both CPU consumption and bandwidth in preparing and sending the response data.

The only URL that should be hardcoded (or preferably kept in a user preference) in the client application is the URL to the service document.

Authentication

AMOv3 cookie session ID

HTTP basic auth with email/pass

Status Codes

Based on HTTP/1.1 Status Code Definitions.

200 OK - Request OK, response body follows.
201 Created - New resource created, response body follows with new content, watch for Location: header containing new resource URL
202 Accepted - The request has been accepted for processing, but the processing has not been completed. Expect an empty response body.
302 Found - The desired resource is more appropriately found at URL supplied by Location: header.
303 See Other - The response reflecting results of this request is found at URL supplied by Location: header.
304 Not Modified - The resource has not changed with respect to the given If-Modified-Since header in the request.
401 Unauthorized - Authentication details not accepted.
403 Forbidden - Authentication details accepted, but request not allowed.
404 Not Found - Resource not found.
405 Method Not Allowed - The method specified is not applicable to the resource.
410 Gone - Usually the status of a successful DELETE request.
415 Unsupported Media Type - Request type not supported - generally only application/x-www-form-urlencoded is accepted.
500 Internal Server Error - Something unexpected went wrong.

Resources

/api/1.3/sharing/

GET - Fetch the service document

Response
- Status: 200 OK
- Content-Type: #Service Document
- Response body varies according to authenticated user's context

/api/1.3/sharing/collections/

POST - Create a new collection

Request
- Content-Type: application/x-www-form-urlencoded
- Parameters:
  - title - human readable title for the collection
  - is_public - whether the collection should be listed in the directory (1) or not (0)

Response
- Status: 201 Created
- Content-Type: #Addon Collection
- Response body will contain collection details, but no addons.
- Location header points to the URL of new collection.
  - i.e. Location: /api/1.3/sharing/collections/5497c4b6-f2e9-11dd-b326-7f8fd4293122

/api/1.3/sharing/collections/{uuid}

GET - Fetch contents of a collection

Response
- Status: 200 OK
- Content-Type: #Addon Collection

POST - Add or update an addon in a collection

Request
- Content-Type: application/x-www-form-urlencoded
- Parameters:
  - guid - GUID of addon to add to list
  - notes - human readable notes about the addon

Response (on success)
- Status: 303 See Other
- Content-Type: #Addon Collection
- Location header points to the URL of new collection.
  - i.e. Location: /api/1.3/sharing/collections/5497c4b6-f2e9-11dd-b326-7f8fd4293122

DELETE - Delete a collection (not implemented)

Response (on success)
- Status: 410 Gone

/api/1.3/sharing/collections/{uuid}/addons/{addon guid}

GET - Fetch details on an addon in a collection

Response (on success)
- Status: 200 OK
- Content-Type: #Addon Collection

PUT - Update details on an addon in a collection

Request
- Content-Type: application/x-www-form-urlencoded
- Parameters:
  - to - comma-separated list of email addresses for notification
  - guid - GUID of addon to share
  - notes - human readable personal notes to be included in notification

Response (on success)
- Content-Type: empty body
- Status: 202 Accepted

DELETE - Remove an addon from a collection

Response (on success)
- Status: 410 Gone

/api/1.3/sharing/email

POST - Request an email sharing notification

Request
- Content-Type: application/x-www-form-urlencoded
- Parameters:
  - to - comma-separated list of email addresses for notification
  - guid - GUID of addon to share
  - notes - human readable personal notes to be included in notification

Response (on success)
- Content-Type: empty body
- Status: 202 Accepted

Representations

Service Document

   <?xml version="1.0" encoding="utf-8" ?>
   <sharing xmlns="http://addons.mozilla.org/" 
           xml:base="http://addons.mozilla.org/api/1.3/sharing/">
       <email href="email" />
       <collections href="collections">
           <collection 
               href="collections/98404f20-f2e0-11dd-9121-3307c31c9566" 
               title="My Laptop Addons"
               creator="lorchard@mozilla.com"
               writable="yes" subscribed="yes" 
               lastmodified="2009-01-04T00:10:00Z" />
           <collection 
               href="collections/9f534614-f2e5-11dd-a55a-2bd072fc4ff4"
               title="Joe's Blogging Addons"
               creator="joe@example.com"
               writable="no" subscribed="yes" 
               lastmodified="2009-01-04T00:10:00Z" />
           <collection 
               href="collections/9f534614-f2e5-11dd-a55a-2bd072fc4ff4"
               title="Invisible Addon Collection"
               creator="lorchard@mozilla.com"
               writable="yes" subscribed="no" 
               lastmodified="2009-01-04T00:10:00Z" />
       </collections>
   </sharing>

Addon Collection

   <?xml version="1.0" encoding="utf-8" ?>
   <collection xmlns="http://addons.mozilla.org/" 
       xml:base="http://addons.mozilla.org/api/1.3/sharing/">
       href="collections/98404f20-f2e0-11dd-9121-3307c31c9566" 
       title="My Laptop Addons"
       writable="yes" subscribed="yes" 
       lastmodified="2009-01-04T00:10:00Z">
       <addon href="collections/98404f20-f2e0-11dd-9121-3307c31c9566/addons/AE93811A-5C9A-4d34-8462-F7B864FC4696">
           <meta>
               <added>2009-01-04T00:00:12Z</added>
               <comments>Here are my nifty comments</comments>
           </meta>
           <categories>
               <category id="1">Feeds, News & Blogging</category>
               <category id="13">Search Tools</category>
               <category id="22">Bookmarks</category>
               <category id="71">Social & Communication</category>
               <category id="92">Toolbars</category>
           </categories>
           <name>StumbleUpon</name>
           <type id="1">Extension</type>
           <guid>{AE93811A-5C9A-4d34-8462-F7B864FC4696}</guid>
           <version>50706</version>
           <status id="4">Public</status>
           <authors>
               <author>StumbleUpon </author>
           </authors>      
           <summary>
               StumbleUpon discovers web sites based on your interests, learns
               what you like and brings you more.
           </summary>
           <description>
               With StumbleUpon you can also connect with friends and share
               your discoveries, meet people that have similar interests, and
               check out what other people are discovering.
           </description>
           <icon>https://addons.mozilla.org/en-US/firefox/images/addon_icon/138/1216845032</icon>
           <compatible_applications>
               <application>
                   <name>Firefox</name>
                   <application_id>1</application_id>
                   <min_version>1.0</min_version>
                   <max_version>3.1a2pre</max_version>
                   <appID>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</appID>
               </application>
               <application>
                   <name>SeaMonkey</name>
                   <application_id>59</application_id>
                   <min_version>1.0</min_version>
                   <max_version>2.0a1</max_version>
                   <appID>{92650c4d-4b8e-4d2a-b7eb-24ecf4f6b63a}</appID>
               </application>
           </compatible_applications>      
           <all_compatible_os>
               <os>ALL</os>
           </all_compatible_os>
           <eula></eula>
           <thumbnail>https://addons.mozilla.org/en-US/firefox/images/t/23099/1215517056</thumbnail>
           <rating>5</rating>
           <learnmore>https://addons.mozilla.org/addon/138</learnmore>
           <install hash="sha256:2e69bcd3db46521e83eb2d5fdf37724c2af33bb1742f86d0e2cbd938c9bcfae4" 
               os="ALL">https://addons.mozilla.org/downloads/file/34258/stumbleupon-3.26-fx+mz+sm.xpi</install>          
       </addon>

   </collection>

Addon

   <?xml version="1.0" encoding="utf-8" ?>
   <addon
       xml:base="http://addons.mozilla.org/api/1.3/sharing/">
       href="collections/98404f20-f2e0-11dd-9121-3307c31c9566/addons/AE93811A-5C9A-4d34-8462-F7B864FC4696">
       <meta>
           <added>2009-01-04T00:00:12Z</added>
           <comments>Here are my nifty comments</comments>
       </meta>
       <categories>
           <category id="1">Feeds, News & Blogging</category>
           <category id="13">Search Tools</category>
           <category id="22">Bookmarks</category>
           <category id="71">Social & Communication</category>
           <category id="92">Toolbars</category>
       </categories>
       <name>StumbleUpon</name>
       <type id="1">Extension</type>
       <guid>{AE93811A-5C9A-4d34-8462-F7B864FC4696}</guid>
       <version>50706</version>
       <status id="4">Public</status>
       <authors>
           <author>StumbleUpon </author>
       </authors>      
       <summary>
           StumbleUpon discovers web sites based on your interests, learns
           what you like and brings you more.
       </summary>
       <description>
           With StumbleUpon you can also connect with friends and share
           your discoveries, meet people that have similar interests, and
           check out what other people are discovering.
       </description>
       <icon>https://addons.mozilla.org/en-US/firefox/images/addon_icon/138/1216845032</icon>
       <compatible_applications>
           <application>
               <name>Firefox</name>
               <application_id>1</application_id>
               <min_version>1.0</min_version>
               <max_version>3.1a2pre</max_version>
               <appID>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</appID>
           </application>
           <application>
               <name>SeaMonkey</name>
               <application_id>59</application_id>
               <min_version>1.0</min_version>
               <max_version>2.0a1</max_version>
               <appID>{92650c4d-4b8e-4d2a-b7eb-24ecf4f6b63a}</appID>
           </application>
       </compatible_applications>      
       <all_compatible_os>
           <os>ALL</os>
       </all_compatible_os>
       <eula></eula>
       <thumbnail>https://addons.mozilla.org/en-US/firefox/images/t/23099/1215517056</thumbnail>
       <rating>5</rating>
       <learnmore>https://addons.mozilla.org/addon/138</learnmore>
       <install hash="sha256:2e69bcd3db46521e83eb2d5fdf37724c2af33bb1742f86d0e2cbd938c9bcfae4" 
           os="ALL">https://addons.mozilla.org/downloads/file/34258/stumbleupon-3.26-fx+mz+sm.xpi</install>          
   </addon>