User:LesOrchard/BandwagonAPI: Difference between revisions

Jump to navigation Jump to search

User:LesOrchard/BandwagonAPI (view source)

Revision as of 21:35, 17 February 2009

683 bytes removed ,  17 February 2009
no edit summary
No edit summary
No edit summary
Line 2: Line 2:


=== Open Questions ===
=== 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. [[User:Fligtar|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. [[User:LesOrchard|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. [[User:LesOrchard|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.
* 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.
Line 12: Line 7:
*** Can we get details on that field added to the product spec, along with maybe how it would affect the web frontend? [[User:LesOrchard|LesOrchard]] 22:24, 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? [[User:LesOrchard|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?
=== Implementation Notes ===
** 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. [[User:Fligtar|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) [[User:Fligtar|Fligtar]] 22:09, 5 February 2009 (UTC)


=== Implementation Notes ===
==== Use URLs as resource identifiers ====


This API spec uses the  
This API spec uses the  
Line 31: Line 23:
of the API, it will also make the client resilient to other more granular
of the API, it will also make the client resilient to other more granular
changes in the server URL space.
changes in the server URL space.
==== Use xml:base to resolve relative URLs ====


The URLs in response data may be supplied as relative paths, or
The URLs in response data may be supplied as relative paths, or
relative with respect an URL indicated by an  
relative with respect an URL indicated by an  
[http://www.w3.org/TR/2001/REC-xmlbase-20010627/#syntax xml:base attribute].
[http://www.w3.org/TR/2001/REC-xmlbase-20010627/#syntax xml:base attribute],
usually supplied by the root node of the response document.
 
==== Use conditional GET ====


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 44: Line 41:
can 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.
==== HTTP Method Override Hack ====
This API uses the HTTP methods GET, POST, PUT, DELETE, and OPTIONS.  Some
incomplete HTTP clients support only GET and POST methods.  So, this API
supports the use of POST as a stand-in for any method other than GET, with
the actual desired HTTP method supplied via one of the following
conventions:
* A URL query parameter named <tt>_method</tt>
* A POST parameter named <tt>_method</tt>
* The value of a header named <tt>X-HTTP-Method-Override</tt>


=== Authentication ===
=== Authentication ===
Line 69: Line 78:
password for that account must be supplied.
password for that account must be supplied.


One use case for this authentication method is for simpler testing not
An example use case for this authentication method is for simpler testing without
entirely dependent on website login.
the need to perform a website login and get a cookie.


=== Authorization ===
=== Authorization ===
Line 84: Line 93:
will receive responses with a <tt>405 Method Not Allowed</tt> status code,  
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.
and the <tt>Allow:</tt> header will list which methods ''are'' allowed.
=== Status Codes ===
Based on [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP/1.1 Status Code Definitions].
* <tt>200 OK</tt> - Request OK, response body follows.
* <tt>201 Created</tt> - New resource created, response body follows with new content, watch for <tt>Location:</tt> header containing new resource URL
* <tt>202 Accepted</tt> - The request has been accepted for processing, but the processing has not been completed.  Expect an empty response body.
* <tt>302 Found</tt> - The desired resource is more appropriately found at URL supplied by <tt>Location:</tt> header.
* <tt>303 See Other</tt> - The response reflecting results of this request is found at URL supplied by <tt>Location:</tt> header.
* <tt>304 Not Modified</tt> - The resource has not changed with respect to the given <tt>If-Modified-Since</tt> header in the request.
* <tt>400 Bad Request</tt> - The request is bad, usually due to invalid fields.
* <tt>401 Unauthorized</tt> - Authentication details not accepted.
* <tt>403 Forbidden</tt> - Authentication details accepted, but request not allowed.
* <tt>404 Not Found</tt> - Resource not found.
* <tt>405 Method Not Allowed</tt> - The method specified is not applicable to the resource.
* <tt>409 Conflict</tt> - The request conflicts with the state of the resource.
* <tt>410 Gone</tt> - Usually the status of a successful DELETE request.
* <tt>415 Unsupported Media Type</tt> - Request type not supported - generally only <tt>application/x-www-form-urlencoded</tt> is accepted.
* <tt>500 Internal Server Error</tt> - Something unexpected went wrong.


=== Resources ===
=== Resources ===
Line 111: Line 100:
literal use as templates in the client application.
literal use as templates in the client application.


==== /api/sharing/ ====
==== Service Document - /api/sharing/ ====


This [[#Service Document|service document]] is the main entry point URL for the
This [[#Service Document|service document]] is the main entry point URL for the
Line 134: Line 123:
** Response body varies according to authenticated user's context
** Response body varies according to authenticated user's context


==== /api/sharing/collections/ ====
==== Collections List - /api/sharing/collections/ ====


This resource represents the set of all shared collections.   
This resource represents the set of all shared collections.   
Line 155: Line 144:
** Location header points to the URL of new collection.
** Location header points to the URL of new collection.


==== /api/sharing/collections/{uuid} ====
==== Collection - /api/sharing/collections/{uuid} ====


This resource represents a single collection of shared addons.
This resource represents a single collection of shared addons.
Line 172: Line 161:
** Parameters:
** Parameters:
*** <tt>guid</tt> - GUID of addon to add to list
*** <tt>guid</tt> - GUID of addon to add to list
*** <tt>notes</tt> - (optional) human readable notes about the addon
*** <tt>comments</tt> - (optional) human readable comments about the addon


* Response (on success)  
* Response (on success)  
Line 179: Line 168:
** Location header points to the URL of the addon resource in the collection.
** Location header points to the URL of the addon resource in the collection.


* Response (if addon already added)
* Response (if addon already present in collection)
** Status: 409 Conflict
** Status: 409 Conflict
** Content-Type: [[#Error Document]]  
** Content-Type: [[#Error Document]]  
Line 188: Line 177:
** Status: <tt>410 Gone</tt>
** Status: <tt>410 Gone</tt>


==== /api/sharing/collections/{uuid}/addons/{addon guid} ====
==== Addon in Collection - /api/sharing/collections/{uuid}/addons/{addon guid} ====


This resource represents a single addon shared in a collection.
This resource represents a single addon shared in a collection.
Line 197: Line 186:
* Response (on success)
* Response (on success)
** Status: <tt>200 OK</tt>
** Status: <tt>200 OK</tt>
** Content-Type: [[#Addon Collection]]
** Content-Type: [[#Addon]]
 
===== PUT - Update addon details in a collection =====
 
* Request
** Content-Type: <tt>application/x-www-form-urlencoded</tt>
** Parameters:
*** <tt>comments</tt> - human readable comments about the addon
 
* Response (on success)
** Status: <tt>200 OK</tt>
** Content-Type: [[#Addon]]
** Response content reflects changes to addon in collection


===== DELETE - Remove an addon from a collection =====
===== DELETE - Remove an addon from a collection =====
Line 207: Line 208:
** Location header points to the URL of collection, which will reflect the addition or update of the addon.
** Location header points to the URL of collection, which will reflect the addition or update of the addon.


==== /api/sharing/email ====
==== Email Sharing - /api/sharing/email ====


This resource offers a general-purpose interface to notification
This resource offers a general-purpose interface to notification
Line 220: Line 221:
*** <tt>to</tt> - comma-separated list of email addresses for notification
*** <tt>to</tt> - comma-separated list of email addresses for notification
*** <tt>guid</tt> - GUID of addon to share
*** <tt>guid</tt> - GUID of addon to share
*** <tt>notes</tt> - human readable personal notes to be included in notification
*** <tt>comments</tt> - human readable personal comments to be included in notification


* Response (on success)
* Response (on success)
** Content-Type: empty body
** Content-Type: empty body
** Status: <tt>202 Accepted</tt>
** Status: <tt>202 Accepted</tt>
=== Status Codes ===
Based on [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP/1.1 Status Code Definitions].
* <tt>200 OK</tt> - Request OK, response body follows.
* <tt>201 Created</tt> - New resource created, response body follows with new content, watch for <tt>Location:</tt> header containing new resource URL
* <tt>202 Accepted</tt> - The request has been accepted for processing, but the processing has not been completed.  Expect an empty response body.
* <tt>302 Found</tt> - The desired resource is more appropriately found at URL supplied by <tt>Location:</tt> header.
* <tt>303 See Other</tt> - The response reflecting results of this request is found at URL supplied by <tt>Location:</tt> header.
* <tt>304 Not Modified</tt> - The resource has not changed with respect to the given <tt>If-Modified-Since</tt> header in the request.
* <tt>400 Bad Request</tt> - The request is bad, usually due to invalid fields.
* <tt>401 Unauthorized</tt> - Authentication details not accepted.
* <tt>403 Forbidden</tt> - Authentication details accepted, but request not allowed.
* <tt>404 Not Found</tt> - Resource not found.
* <tt>405 Method Not Allowed</tt> - The method specified is not applicable to the resource.
* <tt>409 Conflict</tt> - The request conflicts with the state of the resource.
* <tt>410 Gone</tt> - Usually the status of a successful DELETE request.
* <tt>415 Unsupported Media Type</tt> - Request type not supported - generally only <tt>application/x-www-form-urlencoded</tt> is accepted.
* <tt>500 Internal Server Error</tt> - Something unexpected went wrong.


=== Representations ===
=== Representations ===
Line 426: Line 447:
             os="ALL">https://addons.mozilla.org/downloads/file/34258/stumbleupon-3.26-fx+mz+sm.xpi</install>           
             os="ALL">https://addons.mozilla.org/downloads/file/34258/stumbleupon-3.26-fx+mz+sm.xpi</install>           
     </addon>
     </addon>
=== Examples ===
This API can be exercised using [http://curl.haxx.se/ cURL] at a command line:
LesOrchard
Confirmed users
920

edits

Retrieved from "https://wiki.mozilla.org/Special:MobileDiff/129097"

Navigation menu