User:LesOrchard/BandwagonAPI: Difference between revisions

Jump to navigation Jump to search

User:LesOrchard/BandwagonAPI (view source)

Revision as of 19:33, 4 February 2009

11,684 bytes added ,  4 February 2009
m
progress
m (progress)
Line 1: Line 1:
== Bandwagon API ==
== Bandwagon API ==
=== Implementation Notes ===
This API uses the
[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.
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
constructing them on the client side from templates.
For <tt>GET</tt> requests, be sure to retain the value of the
<tt>Last-Modified</tt> header in responses and include it as
<tt>If-Modified-Since</tt> in requests.  This enables
[http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.3 conditional GET]
and may result in <tt>304 Not Modified</tt> 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 [[#.2Fapi.2F1.3.2Fsharing.2F|service document]].


=== Authentication ===
=== Authentication ===
Line 7: Line 28:
==== HTTP basic auth with email/pass ====
==== HTTP basic auth with email/pass ====


=== Content Types ===
=== 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>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>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 ===
 
==== /api/1.3/sharing/ ====
 
===== GET - Fetch the service document =====
 
* Response
** Status: <tt>200 OK</tt>
** 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: <tt>application/x-www-form-urlencoded</tt>
** Parameters:
*** <tt>title</tt> - human readable title for the collection
*** <tt>is_public</tt> - whether the collection should be listed in the directory (<tt>1</tt>) or not (<tt>0</tt>)
 
* Response
** Status: <tt>201 Created</tt>
** Content-Type: [[#Addon Collection]]
** Response body will contain collection details, but no addons.
** Location header points to the URL of new collection.
*** i.e. <tt>Location: /api/1.3/sharing/collections/5497c4b6-f2e9-11dd-b326-7f8fd4293122</tt>
 
==== /api/1.3/sharing/collections/{uuid} ====
 
===== GET - Fetch contents of a collection =====
 
* Response
** Status: <tt>200 OK</tt>
** Content-Type: [[#Addon Collection]]
 
===== POST - Add or update an addon in a collection =====
 
* Request
** Content-Type: <tt>application/x-www-form-urlencoded</tt>
** Parameters:
*** <tt>guid</tt> - GUID of addon to add to list
*** <tt>notes</tt> - human readable notes about the addon
 
* Response (on success)
** Status: <tt>303 See Other</tt>
** Content-Type: [[#Addon Collection]]
** Location header points to the URL of new collection.
*** i.e. <tt>Location: /api/1.3/sharing/collections/5497c4b6-f2e9-11dd-b326-7f8fd4293122</tt>
 
===== DELETE - Delete a collection (not implemented) =====
 
* Response (on success)
** Status: <tt>410 Gone</tt>


==== Service Document ====
==== /api/1.3/sharing/collections/{uuid}/addons/{addon guid} ====
 
===== GET - Fetch details on an addon in a collection =====
 
* Response (on success)
** Status: <tt>200 OK</tt>
** Content-Type: [[#Addon Collection]]
 
===== PUT - Update details on an addon in a collection =====
 
* Request
** Content-Type: <tt>application/x-www-form-urlencoded</tt>
** Parameters:
*** <tt>to</tt> - comma-separated list of email addresses for notification
*** <tt>guid</tt> - GUID of addon to share
*** <tt>notes</tt> - human readable personal notes to be included in notification
 
* Response (on success)
** Content-Type: empty body
** Status: <tt>202 Accepted</tt>
 
===== DELETE - Remove an addon from a collection =====


* collections
* Response (on success)
** writable?
** Status: <tt>410 Gone</tt>
** subscribed?
* email sharing URL


  <collections xmlns="http://addons.mozilla.org/">
==== /api/1.3/sharing/email ====
      <collection
          href="http://addons.mozilla.org/api/1.3/sharing/collections/98404f20-f2e0-11dd-9121-3307c31c9566"
          title=""
          writable="yes" subscribed="yes"
          lastmodified="2009-01-04T00:10:00Z" />
      <collection href="http://..."
          title=""
          writable="yes" subscribed="yes"
          lastmodified="2009-01-04T00:10:00Z" />
  </collections>


==== Addon Collection ====
===== POST - Request an email sharing notification =====


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


=== Resources ===
* Response (on success)
** Content-Type: empty body
** Status: <tt>202 Accepted</tt>


==== /api/1.3/sharing/ ====
=== Representations ===


Content Type: [[#Service Document]]
==== Service Document ====


* GET
    <?xml version="1.0" encoding="utf-8" ?>
* POST
    <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>


==== /api/1.3/sharing/collections ====
==== 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 &amp; Blogging</category>
                <category id="13">Search Tools</category>
                <category id="22">Bookmarks</category>
                <category id="71">Social &amp; 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>


==== /api/1.3/sharing/collections/{uuid} ====
    </collection>


==== Addon ====


==== /api/1.3/sharing/subscriptions/{username} ====
    <?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 &amp; Blogging</category>
            <category id="13">Search Tools</category>
            <category id="22">Bookmarks</category>
            <category id="71">Social &amp; 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>
LesOrchard
Confirmed users
920

edits

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

Navigation menu