User:LesOrchard/BandwagonAPI: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
m (progress)
(more progress - need to flesh out representations)
Line 3: Line 3:
=== Implementation Notes ===
=== Implementation Notes ===


This API uses the  
This API spec uses the  
[http://www.google.com/search?q=hypermedia+as+the+engine+of+application+state REST pattern of including resource URLs in responses],  
[http://www.google.com/search?q=hypermedia+as+the+engine+of+application+state REST pattern of including resource URLs in responses],  
rather than database IDs or other identifiers.
rather than database IDs or other identifiers.
This allows the server to control its own namespace, so please
This allows the server to control its own namespace - so please
use the URLs found in <tt>href</tt> attributes to access the API, rather than
use the URLs found in <tt>href</tt> attributes to access the API, rather than
constructing them on the client side from templates.
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 [[#.2Fapi.2F1.3.2Fsharing.2F|service document]].
This will not only make it easy 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
[http://www.w3.org/TR/2001/REC-xmlbase-20010627/#syntax xml:base attribute].


For <tt>GET</tt> requests, be sure to retain the value of the
For <tt>GET</tt> requests, be sure to retain the value of the
Line 16: Line 26:
and may result in <tt>304 Not Modified</tt> responses
and may result in <tt>304 Not Modified</tt> responses
that indicate the resource has not changed since the last fetch.  This
that indicate the resource has not changed since the last fetch.  This
will save in both CPU consumption and bandwidth in preparing
can save in both CPU consumption and bandwidth in preparing
and sending the response data.
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 [[#.2Fapi.2F1.3.2Fsharing.2F|service document]].


=== Authentication ===
=== Authentication ===
Line 27: Line 34:


==== HTTP basic auth with email/pass ====
==== HTTP basic auth with email/pass ====
=== 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 <tt>403 Forbidden</tt>
status code.
Attempts to manipulate resources for which the user has ''some'' permission
will receive responses with a <tt>405 Method Not Allowed</tt> status code,
and the <tt>Allow:</tt> header will list which methods ''are'' allowed.


=== Status Codes ===
=== Status Codes ===
Line 48: Line 68:
=== Resources ===
=== Resources ===


==== /api/1.3/sharing/ ====
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 is the main entry point URL for the API.  Examples might look something
like the following:
 
    http://localhost/~lorchard/addons/api/sharing
    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
 
The [[#Service Document|service document]] given as a response to a GET
request to the resource will supply URLs leading into the rest of the API.


===== GET - Fetch the service document =====
===== GET - Fetch the service document =====
Line 57: Line 92:
** Response body varies according to authenticated user's context
** Response body varies according to authenticated user's context


==== /api/1.3/sharing/collections/ ====
==== /api/sharing/collections/ ====
 
This resource represents the set of all collections shared.


===== POST - Create a new collection =====
===== POST - Create a new collection =====
Line 74: Line 111:
*** i.e. <tt>Location: /api/1.3/sharing/collections/5497c4b6-f2e9-11dd-b326-7f8fd4293122</tt>
*** i.e. <tt>Location: /api/1.3/sharing/collections/5497c4b6-f2e9-11dd-b326-7f8fd4293122</tt>


==== /api/1.3/sharing/collections/{uuid} ====
==== /api/sharing/collections/{uuid} ====
 
This resource represents a single collection of shared addons.


===== GET - Fetch contents of a collection =====
===== GET - Fetch contents of a collection =====
Line 92: Line 131:
* Response (on success)  
* Response (on success)  
** Status: <tt>303 See Other</tt>
** Status: <tt>303 See Other</tt>
** Content-Type: [[#Addon Collection]]
** Content-Type: empty body
** Location header points to the URL of new collection.
** Response body will be empty.
** Location header points to the URL of collection, which will reflect the addition or update of the addon.
*** i.e. <tt>Location: /api/1.3/sharing/collections/5497c4b6-f2e9-11dd-b326-7f8fd4293122</tt>
*** i.e. <tt>Location: /api/1.3/sharing/collections/5497c4b6-f2e9-11dd-b326-7f8fd4293122</tt>


===== DELETE - Delete a collection (not implemented) =====
===== DELETE - Delete a collection =====


* Response (on success)
* Response (on success)
** Status: <tt>410 Gone</tt>
** Status: <tt>410 Gone</tt>


==== /api/1.3/sharing/collections/{uuid}/addons/{addon guid} ====
==== /api/sharing/collections/{uuid}/addons/{addon guid} ====
 
This resource represents a single addon shared in a collection.


===== GET - Fetch details on an addon in a collection =====
===== GET - Fetch details on an addon in a collection =====
Line 127: Line 169:
** Status: <tt>410 Gone</tt>
** Status: <tt>410 Gone</tt>


==== /api/1.3/sharing/email ====
==== /api/sharing/email ====
 
This resource offers a general-purpose interface to notification
functionality for sharing addons via email messages.


===== POST - Request an email sharing notification =====
===== POST - Request an email sharing notification =====
Line 145: Line 190:


==== Service Document ====
==== 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" ?>
     <?xml version="1.0" encoding="utf-8" ?>

Revision as of 20:02, 4 February 2009

Bandwagon API

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 easy 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

AMOv3 cookie session ID

HTTP basic auth with email/pass

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 is the main entry point URL for the API. Examples might look something like the following: 

   http://localhost/~lorchard/addons/api/sharing
   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

The service document given as a response to a GET request to the resource will supply URLs leading into the rest of the API.

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 collections shared.

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/sharing/collections/{uuid}

This resource represents a single collection of shared addons.

GET - Fetch contents of a 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: empty body
    • Response body will be empty.
    • Location header points to the URL of collection, which will reflect the addition or update of the addon.
      • i.e. Location: /api/1.3/sharing/collections/5497c4b6-f2e9-11dd-b326-7f8fd4293122
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.

GET - Fetch details on an addon in a 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/sharing/email

This resource offers a general-purpose interface to notification functionality for sharing addons via email messages.

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>
           </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>
Retrieved from "https://wiki.allizom.org/index.php?title=User:LesOrchard/BandwagonAPI&oldid=127195"