Confirmed users
920
edits
User:LesOrchard/BandwagonAPI: Difference between revisions
Jump to navigation
Jump to search
more progress - need to flesh out representations
LesOrchard (talk | contribs) m (progress) |
LesOrchard (talk | contribs) (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 | 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 | ||
can save in both CPU consumption and bandwidth in preparing | |||
and sending the response data. | and sending the response data. | ||
=== 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 | ==== /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 | ==== /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: | ** Content-Type: empty body | ||
** Location header points to the URL of | ** 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 | ===== DELETE - Delete a collection ===== | ||
* Response (on success) | * Response (on success) | ||
** Status: <tt>410 Gone</tt> | ** Status: <tt>410 Gone</tt> | ||
==== /api | ==== /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 | ==== /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" ?> | ||