User:LesOrchard/BandwagonAPI: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
Line 162: Line 162:
** Content-Type: [[#Addon Collection]]
** Content-Type: [[#Addon Collection]]


===== POST - Add an addon to a collection =====
===== POST - Add an addon to a collection or overwrite existing details =====


* Request  
* Request  

Revision as of 22:34, 5 February 2009

Bandwagon API

Open Questions

  • How much detail about addons in collection responses is necessary for display in the extension? The less, the better, since building full addon records is expensive.
    • Add-on details only need to be included in the /api/sharing/collections/{uuid} method. I also don't think the /api/sharing/collections/{uuid}/addons/{addon guid} is necessary. Fligtar 22:10, 5 February 2009 (UTC)
      • Well, the question was, can we supply a minimal set of addon details in a GET /api/sharing/collections/{uuid} request for display in the addon - and if so, what's that minimal set? One of the performance issues I originally ran into with the earlier API bugs is that assembling more than 3-4 addons worth of full details can be a bear given all the joins and Cake model code. LesOrchard 22:24, 5 February 2009 (UTC)
      • Also, the /api/sharing/collections/{uuid}/addons/{addon guid} resource is necessary for the HTTP DELETE method, if we want to delete addons from collections. And if we can use a minimal set in the collection list, an HTTP GET method on this resource will return the full details for an individual addon in a collection. LesOrchard 22:24, 5 February 2009 (UTC)
  • Product spec calls for ability to create collections for "auto-publishers" to sync with list of addons in browser. How is this distinguished from creating a collection in general, or is a distinction even necessary? Seems like the distinction of an auto-publisher lies mainly in the extension.
    • There should probably be a field that says what type of collection something is (normal, editors pick, auto-publisher), but apart from that field, there's no difference on the API side of CRUD operations. Right now, we're only expecting auto-publishers to use the API for creation. Fligtar 22:10, 5 February 2009 (UTC)
      • Can we get details on that field added to the product spec, along with maybe how it would affect the web frontend? LesOrchard 22:24, 5 February 2009 (UTC)
  • Deleting a collection is not in the product spec, but might be useful down the road and for testing. Any harm in including it?
    • The current plan only involves deleting collections from the web interface, but no, no harm in including it. We may want to be able to delete auto-publisher collections from the extension. Fligtar 22:10, 5 February 2009 (UTC)
  • With the addition of authentication, we know what user published an add-on to a collection. This should be stored, and included in the API output, probably in the same name format as we use for extension authors (nickname if set, otherwise first and last name, I believe) Fligtar 22:09, 5 February 2009 (UTC)

Implementation Notes

This API spec 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.

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. This will not only make it easier to switch between production, staging, and dev instances of the API, it will also make the client resilient to other more granular changes in the server URL space.

The URLs in response data may be supplied as relative paths, or relative with respect an URL indicated by an xml:base attribute.

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 can save in both CPU consumption and bandwidth in preparing and sending the response data.

Authentication

All API access requires authentication.

AMOv3 cookie session ID

If a Cookie: header is sent with the value of an AMOv3 login session ID, that value will be validated first in authenticating the user.

Example header, with the AMOv3 cookie among other cookies: 

   Cookie: foo=bar; AMOv3=865ikpjmn6bqh897msr3o5hv12; baz=quux

The primary use-case for this means of authentication is in a browser extension with access to the user's cookie jar and the ability to extract the same cookie used for website login.

HTTP basic auth with email/pass

If no AMOv3 cookie header is found, or if it is invalid, an attempt to authenticate the user with HTTP basic auth will be made. The username is expected to be an email address registered with AMO and the correct password for that account must be supplied.

One use case for this authentication method is for simpler testing not entirely dependent on website login.

Authorization

In general, the client will not be given the URLs of resources to which the authenticated user does not have at least some access (ie. GET-only).

Attempts to manipulate resources to which the authenticated user does not have any permission do to so will receive a response with a 403 Forbidden status code.

Attempts to manipulate resources for which the user has some permission will receive responses with a 405 Method Not Allowed status code, and the Allow: header will list which methods are allowed.

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

The following is a catalog of the kinds of resources made available by the API. The URL paths used as headers are conceptual examples, not intended for literal use as templates in the client application.

/api/sharing/

This service document is the main entry point URL for the API. Polling it periodically, with proper attention to Last-Modified and If-Modified-Since headers, should offer a relatively efficient way to track collection subscriptions and what subscriptions are writable.

Beyond collections, the service document will supply URLs leading into the rest of the API. (eg. email sharing)

Concrete examples of this URL might look something like the following: 

   http://localhost/~lorchard/addons/api.php?action=service_doc
   http://dev.addons.mozilla.com/en-US/firefox/api/1.3/sharing
   https://preview.addons.mozilla.org/en-US/firefox/api/1.3/sharing
   https://addons.mozilla.org/en-US/firefox/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/sharing/collections/

This resource represents the set of all shared collections. A concrete URL for this resource can be acquired from the #Service Document.

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 the data for the freshly created collection.
    • Location header points to the URL of new collection.

/api/sharing/collections/{uuid}

This resource represents a single collection of shared addons. A concrete URL for this kind of resource can be acquired from the #Service Document.

GET - Fetch contents of a collection
POST - Add an addon to a collection or overwrite existing details
  • Request
    • Content-Type: application/x-www-form-urlencoded
    • Parameters:
      • guid - GUID of addon to add to list
      • notes - (optional) human readable notes about the addon
  • Response (on success)
    • Status: 303 See Other
    • Content-Type: #Addon Collection
    • Response body will reflect the change to the collection with addon added or updated.
    • Location header points to the URL of collection, which will reflect the addition or update of the addon.
DELETE - Delete a collection
  • Response (on success)
    • Status: 410 Gone

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

This resource represents a single addon shared in a collection. A concrete URL for this kind of resource can be acquired from an #Addon Collection.

GET - Fetch details on an addon in a collection
DELETE - Remove an addon from a collection
  • Response (on success)
    • Status: 303 See Other
    • Content-Type: #Addon Collection
    • Response body will reflect the change to the collection with addon added or updated.
    • Location header points to the URL of collection, which will reflect the addition or update of the addon.

/api/sharing/email

This resource offers a general-purpose interface to notification functionality for sharing addons via email messages. A concrete URL for this of resource can be acquired from the #Service Document.

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

The service document is the main entry point, or "front door" to the API, providing links to other resources exposed by the API and offering an overview of what particular resources are made available to the authenticated user. 

   <?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>
               <addedby>Les Orchard</addedby>
           </meta>
           <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>
           <thumbnail>https://addons.mozilla.org/en-US/firefox/images/t/23099/1215517056</thumbnail>
           <rating>5</rating>
           <learnmore>https://addons.mozilla.org/addon/138</learnmore>
       </addon>
       <addon>
           <meta>
               <added>2009-01-02T00:00:12Z</added>
               <addedby>Nick Nguyen</addedby>
               <comments>You should really use this.</comments>
           </meta>
           <name>FoxyTunes</name>
           <type id="1">Extension</type>
           <guid>{463F6CA5-EE3C-4be1-B7E6-7FEE11953374}</guid>
           <version>50845</version>
           <status id="4">Public</status>
           <authors>
               <author>Alex Sirota</author>
               <author>Yahoo! Inc. </author>
           </authors>      
           <summary>
               Do you listen to Music while surfing the Web?^M^MFoxyTunes lets
               you control almost any media player and find lyrics, covers,
               videos, bios and much more with a click right from your
               browser.
           </summary>
           <description>
               Do you listen to Music while surfing the Web?FoxyTunes lets
               you control almost any media player and find lyrics, covers,
               videos, bios and much more with a click right from your
               browser.Supports WinAmp, iTunes, Yahoo Music Engine,
               Pandora, foobar2000, Windows Media Player, Xbox Media Center,
               Musicmatch, Quintessential, J. River, jetAudio, XMPlay,
               MediaMonkey, Media Player Classic, Sonique, wxMusik, Real
               Player, XMMS, Noatun, Juk, Amarok, Music Player Daemon,
               Rhythmbox and many other players.Just click on the orange
               note and select your player.CNET Editor's Rating: 5/5
               starsPC Magazine: Top 15 Firefox ExtensionsPC World: Top
               Download Picks 
           </description>
           <icon>https://addons.mozilla.org/en-US/firefox/images/addon_icon/219/1226633195</icon>
           <thumbnail>https://addons.mozilla.org/en-US/firefox/images/t/20256/1209472104</thumbnail>
           <rating>5</rating>
           <learnmore>https://addons.mozilla.org/addon/219</learnmore>
       </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>
           <addedby>Les Orchard</addedby>
           <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>
Retrieved from "https://wiki.allizom.org/index.php?title=User:LesOrchard/BandwagonAPI&oldid=127529"