MozillaWiki

User:LesOrchard/BandwagonAPI: Difference between revisions

User page Discussion

User:LesOrchard/BandwagonAPI (view source)

Revision as of 20:23, 31 March 2009

16,711 bytes added ,  31 March 2009
no edit summary
No edit summary
 
(13 intermediate revisions by the same user not shown)
Line 1: Line 1:
== Bandwagon API ==
== Bandwagon API ==


=== Open Questions ===
=== Implementation Notes ===
 
* 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)
 
* 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. [[User:Fligtar|Fligtar]] 22:10, 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. [[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)
==== Use URLs as resource identifiers ====
 
=== Implementation Notes ===


This API spec uses the  
This API spec uses the  
Line 28: Line 17:
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 41: Line 35:
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 66: Line 72:
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 81: Line 87:
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>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 ===
=== Resources ===
Line 106: Line 94:
literal use as templates in the client application.
literal use as templates in the client application.


==== /api/sharing/ ====
Also note that not all HTTP methods are avalable for every resource.
 
==== 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 129: Line 119:
** 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.   
A concrete URL for this resource can be acquired from the [[#Service Document]].
A concrete URL for this resource can be acquired from the [[#Service Document]].
Note that the GET method is not currently implemented, because the service doc
and individual collection docs provide the information that would conceivably
be made available.  Someday, this could be an interface on the public
collection directory.


===== POST - Create a new collection =====
===== POST - Create a new collection =====
Line 139: Line 134:
** Content-Type: <tt>application/x-www-form-urlencoded</tt>
** Content-Type: <tt>application/x-www-form-urlencoded</tt>
** Parameters:
** Parameters:
*** <tt>title</tt> - human readable title for the collection
*** <tt>name</tt> - human readable name for the collection
*** <tt>is_public</tt> - whether the collection should be listed in the directory (<tt>1</tt>) or not (<tt>0</tt>)
*** <tt>description</tt> - human readable longer description for the collection
*** <tt>nickname</tt> - unique nickname for collection usable in URLs
*** <tt>listed</tt> - whether the collection should be listed in the directory (<tt>1</tt>) or not (<tt>0</tt>)


* Response  
* Response  
Line 148: Line 145:
** 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 159: Line 156:
** Content-Type: [[#Addon Collection]]
** Content-Type: [[#Addon Collection]]


===== POST - Add or update an addon in a collection =====
===== PUT - Update collection details =====
 
Note that this update is limited to collection-specific details, and cannot
modify any of the other data that makes up an addon document.


* Request  
* Request  
** Content-Type: <tt>application/x-www-form-urlencoded</tt>
** Content-Type: <tt>application/x-www-form-urlencoded</tt>
** Parameters:
** Parameters:
*** <tt>guid</tt> - GUID of addon to add to list
*** <tt>name</tt> - human readable name for the collection
*** <tt>notes</tt> - (optional) human readable notes about the addon
*** <tt>description</tt> - human readable longer description for the collection
*** <tt>nickname</tt> - unique nickname for collection usable in URLs
*** <tt>listed</tt> - whether the collection should be listed in the directory (<tt>1</tt>) or not (<tt>0</tt>)


* Response (on success)  
* Response (on success)  
** Status: <tt>303 See Other</tt>
** Status: <tt>200 OK</tt>
** Content-Type: [[#Addon Collection]]
** Content-Type: [[#Addon Collection]]
** Response body will reflect the change to the collection with addon added or updated.
** Response content reflects changes to collection
** Location header points to the URL of collection, which will reflect the addition or update of the addon.


===== DELETE - Delete a collection =====
===== DELETE - Delete a collection =====
Line 178: Line 179:
** Status: <tt>410 Gone</tt>
** Status: <tt>410 Gone</tt>


==== /api/sharing/collections/{uuid}/addons/{addon guid} ====
==== List of Addons in a Collection - /api/sharing/collections/{uuid}/addons/ ====
 
This resource represents addons in a collection.
A concrete URL for this kind of resource can be acquired from the [[#Service Document]].
 
Note that the GET method is not currently implemented, because the parent
collection doc provides the information that would conceivably be made
available.
 
===== POST - Add an addon to a collection =====
 
* Request
** Content-Type: <tt>application/x-www-form-urlencoded</tt>
** Parameters:
*** <tt>guid</tt> - GUID of addon to add to list
*** <tt>comments</tt> - (optional) human readable comments about the addon
 
* Response (on success)
** Status: <tt>201 Created</tt>
** Content-Type: [[#Addon]]
** Response body will contain the data for the freshly added addon.
** Location header points to the URL of the addon resource in the collection.
 
* Response (if addon already present in collection)
** Status: 409 Conflict
** Content-Type: [[#Error Document]]
 
==== Addon in a 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.
A concrete URL for this kind of resource can be acquired from an [[#Addon 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 =====
===== GET - Fetch details on an addon =====


* 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 =====
 
Note that this update is limited to collection-specific details, and cannot
modify any of the other data that makes up an addon document.
 
* 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 197: Line 240:
** 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 210: Line 253:
*** <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 ===
==== Error Document ====
Most errors will be indicated by an HTTP Status in the 400s or 500s, and will
be accompanied by further details in an XML document like the following:
    <?xml version="1.0" encoding="utf-8" ?>
    <error xmlns="http://addons.mozilla.org/"
        reason="some_reason_for_error"
        details="further details for error" />
Reason values to expect include:
* <tt>invalid_parameters</tt>
* <tt>collection_unknown</tt>
* <tt>not_collection_owner</tt>
* <tt>unknown_addon_guid</tt>
* <tt>addon_already_in_collection</tt>
* <tt>addon_not_in_collection</tt>
* <tt>{GET,POST,DELETE,PUT}_not_allowed</tt>
* <tt>unauthorized</tt>
* <tt>not_writable</tt>


==== Service Document ====
==== Service Document ====
Line 232: Line 317:
             <collection  
             <collection  
                 href="collections/98404f20-f2e0-11dd-9121-3307c31c9566"  
                 href="collections/98404f20-f2e0-11dd-9121-3307c31c9566"  
                 title="My Laptop Addons"
                 name="My Laptop Addons"
                description="Longer description yay"
                 creator="lorchard@mozilla.com"
                 creator="lorchard@mozilla.com"
                 writable="yes" subscribed="yes"  
                 writable="yes" subscribed="yes"  
                 lastmodified="2009-01-04T00:10:00Z" />
                 lastmodified="2009-01-04T00:10:00Z">
                    <addons href="collections/98404f20-f2e0-11dd-9121-3307c31c9566/addons/" />
            </collection>
             <collection  
             <collection  
                 href="collections/9f534614-f2e5-11dd-a55a-2bd072fc4ff4"
                 href="collections/9f534614-f2e5-11dd-a55a-2bd072fc4ff4"
                 title="Joe's Blogging Addons"
                 name="Joe's Blogging Addons"
                description="Longer description yay"
                 creator="joe@example.com"
                 creator="joe@example.com"
                 writable="no" subscribed="yes"  
                 writable="no" subscribed="yes"  
                 lastmodified="2009-01-04T00:10:00Z" />
                 lastmodified="2009-01-04T00:10:00Z">
                    <addons href="collections/9f534614-f2e5-11dd-a55a-2bd072fc4ff4/addons/" />
            </collection>
             <collection  
             <collection  
                 href="collections/9f534614-f2e5-11dd-a55a-2bd072fc4ff4"
                 href="collections/9f534614-f2e5-11dd-a55a-2bd072fc4ff4"
                 title="Invisible Addon Collection"
                 name="Invisible Addon Collection"
                description="Longer description yay"
                 creator="lorchard@mozilla.com"
                 creator="lorchard@mozilla.com"
                 writable="yes" subscribed="no"  
                 writable="yes" subscribed="no"  
                 lastmodified="2009-01-04T00:10:00Z" />
                 lastmodified="2009-01-04T00:10:00Z">
                    <addons href="collections/9f534614-f2e5-11dd-a55a-2bd072fc4ff4/addons/" />
            </collection>
         </collections>
         </collections>
     </sharing>
     </sharing>


==== Addon Collection ====
==== Addon Collection ====


     <?xml version="1.0" encoding="utf-8" ?>
     <?xml version="1.0" encoding="utf-8" ?>
     <collection xmlns="http://addons.mozilla.org/"  
     <collection xmlns="http://addons.mozilla.org/"  
             xml:base="http://addons.mozilla.org/api/1.3/sharing/">
             xml:base="http://addons.mozilla.org/api/1.3/sharing/collections/98404f20-f2e0-11dd-9121-3307c31c9566/">
             href="collections/98404f20-f2e0-11dd-9121-3307c31c9566"  
             href="collections/98404f20-f2e0-11dd-9121-3307c31c9566"  
             title="My Laptop Addons"
             name="My Laptop Addons"
            description="Longer description yay"
             writable="yes" subscribed="yes"  
             writable="yes" subscribed="yes"  
             lastmodified="2009-01-04T00:10:00Z">
             lastmodified="2009-01-04T00:10:00Z">
         <addon href="collections/98404f20-f2e0-11dd-9121-3307c31c9566/addons/AE93811A-5C9A-4d34-8462-F7B864FC4696">
         <addons href="addons/">
            <meta>
            <addon href="addons/AE93811A-5C9A-4d34-8462-F7B864FC4696">
                <added>2009-01-04T00:00:12Z</added>
                <meta>
                <comments>Here are my nifty comments</comments>
                    <added>2009-01-04T00:00:12Z</added>
            </meta>
                    <comments>Here are my nifty comments</comments>
            <name>StumbleUpon</name>
                    <addedby>Les Orchard</addedby>
            <type id="1">Extension</type>
                </meta>
            <guid>{AE93811A-5C9A-4d34-8462-F7B864FC4696}</guid>
                <name>StumbleUpon</name>
            <version>50706</version>
                <type id="1">Extension</type>
            <status id="4">Public</status>
                <guid>{AE93811A-5C9A-4d34-8462-F7B864FC4696}</guid>
            <authors>
                <version>50706</version>
                <author>StumbleUpon </author>
                <status id="4">Public</status>
            </authors>       
                <authors>
            <summary>
                    <author>StumbleUpon </author>
                StumbleUpon discovers web sites based on your interests, learns
                </authors>       
                what you like and brings you more.
                <summary>
            </summary>
                    StumbleUpon discovers web sites based on your interests, learns
            <description>
                    what you like and brings you more.
                With StumbleUpon you can also connect with friends and share
                </summary>
                your discoveries, meet people that have similar interests, and
                <description>
                check out what other people are discovering.
                    With StumbleUpon you can also connect with friends and share
            </description>
                    your discoveries, meet people that have similar interests, and
            <icon>https://addons.mozilla.org/en-US/firefox/images/addon_icon/138/1216845032</icon>
                    check out what other people are discovering.
            <thumbnail>https://addons.mozilla.org/en-US/firefox/images/t/23099/1215517056</thumbnail>
                </description>
            <rating>5</rating>
                <icon>https://addons.mozilla.org/en-US/firefox/images/addon_icon/138/1216845032</icon>
            <learnmore>https://addons.mozilla.org/addon/138</learnmore>
                <thumbnail>https://addons.mozilla.org/en-US/firefox/images/t/23099/1215517056</thumbnail>
        </addon>
                <rating>5</rating>
        <addon>
                <learnmore>https://addons.mozilla.org/addon/138</learnmore>
            <meta>
            </addon>
                <added>2009-01-02T00:00:12Z</added>
            <addon>
                <comments>You should really use this.</comments>
                <meta>
            </meta>
                    <added>2009-01-02T00:00:12Z</added>
            <name>FoxyTunes</name>
                    <addedby>Nick Nguyen</addedby>
            <type id="1">Extension</type>
                    <comments>You should really use this.</comments>
            <guid>{463F6CA5-EE3C-4be1-B7E6-7FEE11953374}</guid>
                </meta>
            <version>50845</version>
                <name>FoxyTunes</name>
            <status id="4">Public</status>
                <type id="1">Extension</type>
            <authors>
                <guid>{463F6CA5-EE3C-4be1-B7E6-7FEE11953374}</guid>
                <author>Alex Sirota</author>
                <version>50845</version>
                <author>Yahoo! Inc. </author>
                <status id="4">Public</status>
            </authors>       
                <authors>
            <summary>
                    <author>Alex Sirota</author>
                Do you listen to Music while surfing the Web?^M^MFoxyTunes lets
                    <author>Yahoo! Inc. </author>
                you control almost any media player and find lyrics, covers,
                </authors>       
                videos, bios and much more with a click right from your
                <summary>
                browser.
                    Do you listen to Music while surfing the Web?^M^MFoxyTunes lets
            </summary>
                    you control almost any media player and find lyrics, covers,
            <description>
                    videos, bios and much more with a click right from your
                Do you listen to Music while surfing the Web?FoxyTunes lets
                    browser.
                you control almost any media player and find lyrics, covers,
                </summary>
                videos, bios and much more with a click right from your
                <description>
                browser.Supports WinAmp, iTunes, Yahoo Music Engine,
                    Do you listen to Music while surfing the Web?FoxyTunes lets
                Pandora, foobar2000, Windows Media Player, Xbox Media Center,
                    you control almost any media player and find lyrics, covers,
                Musicmatch, Quintessential, J. River, jetAudio, XMPlay,
                    videos, bios and much more with a click right from your
                MediaMonkey, Media Player Classic, Sonique, wxMusik, Real
                    browser.Supports WinAmp, iTunes, Yahoo Music Engine,
                Player, XMMS, Noatun, Juk, Amarok, Music Player Daemon,
                    Pandora, foobar2000, Windows Media Player, Xbox Media Center,
                Rhythmbox and many other players.Just click on the orange
                    Musicmatch, Quintessential, J. River, jetAudio, XMPlay,
                note and select your player.CNET Editor&#39;s Rating: 5/5
                    MediaMonkey, Media Player Classic, Sonique, wxMusik, Real
                starsPC Magazine: Top 15 Firefox ExtensionsPC World: Top
                    Player, XMMS, Noatun, Juk, Amarok, Music Player Daemon,
                Download Picks  
                    Rhythmbox and many other players.Just click on the orange
            </description>
                    note and select your player.CNET Editor&#39;s Rating: 5/5
            <icon>https://addons.mozilla.org/en-US/firefox/images/addon_icon/219/1226633195</icon>
                    starsPC Magazine: Top 15 Firefox ExtensionsPC World: Top
            <thumbnail>https://addons.mozilla.org/en-US/firefox/images/t/20256/1209472104</thumbnail>
                    Download Picks  
            <rating>5</rating>
                </description>
            <learnmore>https://addons.mozilla.org/addon/219</learnmore>
                <icon>https://addons.mozilla.org/en-US/firefox/images/addon_icon/219/1226633195</icon>
         </addon>
                <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>
         </addons>
     </collection>
     </collection>


Line 333: Line 430:


     <?xml version="1.0" encoding="utf-8" ?>
     <?xml version="1.0" encoding="utf-8" ?>
     <addon xml:base="http://addons.mozilla.org/api/1.3/sharing/"
     <addon xml:base="http://addons.mozilla.org/api/1.3/sharing/collections/98404f20-f2e0-11dd-9121-3307c31c9566/addons/AE93811A-5C9A-4d34-8462-F7B864FC4696">
        href="collections/98404f20-f2e0-11dd-9121-3307c31c9566/addons/AE93811A-5C9A-4d34-8462-F7B864FC4696">
         <meta>
         <meta>
             <added>2009-01-04T00:00:12Z</added>
             <added>2009-01-04T00:00:12Z</added>
            <addedby>Les Orchard</addedby>
             <comments>Here are my nifty comments</comments>
             <comments>Here are my nifty comments</comments>
            <collection href=".." />
         </meta>
         </meta>
         <categories>
         <categories>
Line 390: Line 488:
             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 / Walkthrough ===
This API can be exercised using [http://curl.haxx.se/ cURL] at a command line.
The service URL used in all these examples is:
    http://dev-bandwagon.addons.mozilla.org/en-US/firefox/api/1.3/sharing/
However, this URL will change depending on the actual AMO instance used.
==== Using Cookie Auth ====
You can use session cookie auth with cURL, though it's a little painful.
You'll need an extension like Firebug paired with FireCookie to check cookies
and headers in your browser.
Once you have those, try logging into an AMO install.  You should get a
cookie named "AMOv3".  Copy the value of that cookie and assign it to a
variable in your shell like so:
    $ AUTH_COOKIE=6735160d21d97131f34d86bb1fa5c096
The User-Agent header is another important component, since AMO invalidates
session cookies from a user agent that differs from the one used to login.
This shouldn't be an issue in extension development, but it can cause
destroyed sessions (ie. the user is logged out) when using cURL.
So, check the request header for your User-Agent and assign it to another
shell variable:
    $ USER_AGENT="Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10.5; en-US; rv:1.9.0.6) Gecko/2009011912 Firefox/3.0.6 FirePHP/0.2.4"
Then, you can make your first request to fetch the service document:
    $ curl -sD - -A "$USER_AGENT" -H "Cookie: AMOv3=${AUTH_COOKIE};" -XGET \
        'http://dev-bandwagon.addons.mozilla.org/en-US/firefox/api/1.3/sharing/'
You should see a response like the following:
    HTTP/1.1 200 OK
    Date: Thu, 19 Feb 2009 21:49:07 GMT
    Server: Apache/2.2.8 (Unix) mod_ssl/2.2.8 OpenSSL/0.9.7l DAV/2 PHP/5.2.6
    X-Powered-By: PHP/5.2.6
    X-AMO-ServedBy: quadshot-2.local
    P3P: CP="NOI ADM DEV PSAi COM NAV OUR OTRo STP IND DEM"
    Cache-Control: public, max-age=3600
    Last-modified: Thu, 19 Feb 2009 21:49:07 GMT
    Expires: Thu, 19 Feb 2009 22:49:07 GMT
    Content-Length: 273
    Content-Type: text/xml
   
    <?xml version="1.0" encoding="utf-8" ?>
    <sharing xmlns="http://addons.mozilla.org/" xml:base="http://dev-bandwagon.addons.mozilla.org/en-US/firefox/api/1.3/sharing/">
        <email href="email" />
        <collections href="collections/">
           
        </collections>
    </sharing>
==== Using HTTP Basic Auth ====
When trying out the API with cURL, HTTP Basic Auth is a much easier way to
go.  You can fetch the service document like so:
    $ USER="nobody@mozilla.org"
    $ PASSWD="test"
    $ curl -sD - -u "$USER:$PASSWD" -XGET \
        'http://dev-bandwagon.addons.mozilla.org/en-US/firefox/api/1.3/sharing/'
   
==== Creating a new collection ====
To create a new collection, first fetch the service doc:
    $ curl -sD - -u "$USER:$PASSWD" -XGET \
        'http://dev-bandwagon.addons.mozilla.org/en-US/firefox/api/1.3/sharing/'
   
    HTTP/1.1 200 OK
    Date: Thu, 19 Feb 2009 21:51:30 GMT
    Server: Apache/2.2.8 (Unix) mod_ssl/2.2.8 OpenSSL/0.9.7l DAV/2 PHP/5.2.6
    X-Powered-By: PHP/5.2.6
    X-AMO-ServedBy: quadshot-2.local
    Cache-Control: public, max-age=3600
    Last-modified: Thu, 19 Feb 2009 21:51:31 GMT
    Expires: Thu, 19 Feb 2009 22:51:31 GMT
    Content-Length: 273
    Content-Type: text/xml
   
    <?xml version="1.0" encoding="utf-8" ?>
    <sharing xmlns="http://addons.mozilla.org/"
            xml:base="http://dev-bandwagon.addons.mozilla.org/en-US/firefox/api/1.3/sharing/">
        <email href="email" />
        <collections href="collections/">
           
        </collections>
    </sharing>
   
Note the <tt>xml:base</tt> attribute on <tt>sharing</tt> and the <tt>href</tt>
attribute on <tt>collections</tt>.  Use those together to resolve an
absolute URL, and that's the collections resource URL:
    http://dev-bandwagon.addons.mozilla.org/en-US/firefox/api/1.3/sharing/collections/
Now, you can POST to that URL to create a new collection, like so:
    $ curl -sD - -u "$USER:$PASSWD" -XPOST \
        -d 'nickname=foobar&name=Foo+Bar&description=collection+of+foobar+addons&listed=1' \
        'http://dev-bandwagon.addons.mozilla.org/en-US/firefox/api/1.3/sharing/collections/'
   
    HTTP/1.1 201 Created
    Date: Thu, 19 Feb 2009 22:02:36 GMT
    Server: Apache/2.2.8 (Unix) mod_ssl/2.2.8 OpenSSL/0.9.7l DAV/2 PHP/5.2.6
    X-Powered-By: PHP/5.2.6
    X-AMO-ServedBy: quadshot-2.local
    Location: http://dev-bandwagon.addons.mozilla.org/en-US/firefox/api/1.3/sharing/collections/109/
    Content-Length: 0
    Content-Type: text/html
The creation of the collection was successful.  Note the URL in the <tt>Location:</tt>
header.  That's the URL to the newly created collection resource. 
Try fetching it:
    $ curl -sD - -u "$USER:$PASSWD" -XGET \
        'http://dev-bandwagon.addons.mozilla.org/en-US/firefox/api/1.3/sharing/collections/109'
   
    HTTP/1.1 200 OK
    Date: Thu, 19 Feb 2009 22:04:19 GMT
    Server: Apache/2.2.8 (Unix) mod_ssl/2.2.8 OpenSSL/0.9.7l DAV/2 PHP/5.2.6
    X-Powered-By: PHP/5.2.6
    X-AMO-ServedBy: quadshot-2.local
    Cache-Control: public, max-age=3600
    Last-modified: Thu, 19 Feb 2009 22:04:19 GMT
    Expires: Thu, 19 Feb 2009 23:04:19 GMT
    Content-Length: 396
    Content-Type: text/xml
   
    <?xml version="1.0" encoding="utf-8" ?>
    <collection xmlns="http://addons.mozilla.org/"
        xml:base="http://dev-bandwagon.addons.mozilla.org/en-US/firefox/api/1.3/sharing/collections/109/"
        name="Foo Bar"
        description="collection of foobar addons"
        creator="Sancus"
        listed="yes" writable="yes" subscribed="no"
        lastmodified="2009-02-19T19:05:55-05:00">
   
        <addons href="addons/">
           
        </addons>
   
    </collection>
   
==== Adding an addon to a collection ====
Notice that the new collection offers an <tt>addon</tt> element with an
<tt>href</tt> attribute.  Once resolved using <tt>xml:base</tt>, you can POST
to this URL to add an addon:
    $ curl -sD - -u "$USER:$PASSWD" -XPOST \
        -d 'guid=farming%40microfarmer.org&comments=I+really+like+this+addon' \
        'http://dev-bandwagon.addons.mozilla.org/en-US/firefox/api/1.3/sharing/collections/109/addons/'
   
    HTTP/1.1 201 Created
    Date: Thu, 19 Feb 2009 22:10:50 GMT
    Server: Apache/2.2.8 (Unix) mod_ssl/2.2.8 OpenSSL/0.9.7l DAV/2 PHP/5.2.6
    X-Powered-By: PHP/5.2.6
    X-AMO-ServedBy: quadshot-2.local
    Location: http://dev-bandwagon.addons.mozilla.org/en-US/firefox/api/1.3/sharing/collections/109/addons/farming%40microfarmer.org
    Content-Length: 0
    Content-Type: text/html
And you can GET the URL in the <tt>Location:</tt> header:
    $ curl -sD - -u "$USER:$PASSWD" -XGET \
        'http://dev-bandwagon.addons.mozilla.org/en-US/firefox/api/1.3/sharing/collections/109/addons/farming%40microfarmer.org'
   
    HTTP/1.1 200 OK
    Date: Thu, 19 Feb 2009 22:12:15 GMT
    Server: Apache/2.2.8 (Unix) mod_ssl/2.2.8 OpenSSL/0.9.7l DAV/2 PHP/5.2.6
    X-Powered-By: PHP/5.2.6
    X-AMO-ServedBy: quadshot-2.local
    Cache-Control: public, max-age=3600
    Last-modified: Thu, 19 Feb 2009 22:12:15 GMT
    Expires: Thu, 19 Feb 2009 23:12:15 GMT
    Transfer-Encoding: chunked
    Content-Type: text/xml
       
    <?xml version="1.0" encoding="utf-8" ?>
    <addon xml:base="http://dev-bandwagon.addons.mozilla.org/en-US/firefox/api/1.3/sharing/collections/109/addons/farming%40microfarmer.org">
        <meta>
            <added>2009-02-19T17:10:50-05:00</added>
            <addedby>Sancus</addedby>
            <comments>I really like this addon</comments>
            <collection href=".." />   
        </meta>
        <categories>
            <category id="12">Organizer</category>
            <category id="13">Web Data</category>
        </categories>
        <name>MicroFarmer</name>
        <type id='1'>Extension</type>
        <guid>farming@microfarmer.org</guid>
        <version>9</version>
        <!-- details omitted... -->
    </addon>
A GET request to the collection will show that the addon has been added:
    $ curl -sD - -u "$USER:$PASSWD" -XGET \
        'http://dev-bandwagon.addons.mozilla.org/en-US/firefox/api/1.3/sharing/collections/109/'
   
    HTTP/1.1 200 OK
    Date: Thu, 19 Feb 2009 22:12:15 GMT
    Server: Apache/2.2.8 (Unix) mod_ssl/2.2.8 OpenSSL/0.9.7l DAV/2 PHP/5.2.6
    X-Powered-By: PHP/5.2.6
    X-AMO-ServedBy: quadshot-2.local
    Cache-Control: public, max-age=3600
    Last-modified: Thu, 19 Feb 2009 22:12:15 GMT
    Expires: Thu, 19 Feb 2009 23:12:15 GMT
    Transfer-Encoding: chunked
    Content-Type: text/xml
       
    <?xml version="1.0" encoding="utf-8" ?>
    <collection xmlns="http://addons.mozilla.org/"
        xml:base="http://dev-bandwagon.addons.mozilla.org/en-US/firefox/api/1.3/sharing/collections/109/"
        name="Foo Bar"
        description="collection of foobar addons"
        creator="Sancus"
        listed="yes" writable="yes" subscribed="no"
        lastmodified="2009-02-19T19:05:55-05:00">
   
        <addons href="addons/">
   
            <addon href="addons/farming%40microfarmer.org">
                <meta>
                    <added>2009-02-19T17:10:50-05:00</added>
                    <addedby>Sancus</addedby>
                    <comments>I really like this addon</comments>
                </meta>
                <categories>
                    <category id="12">Organizer</category>
                    <category id="13">Web Data</category>
                </categories>
                <name>MicroFarmer</name>
                <type id='1'>Extension</type>
                <guid>farming@microfarmer.org</guid>
                <version>9</version>
                <!-- details omitted... -->
            </addon>
           
        </addons>
   
    </collection>
==== Updating an addon in a collection ====
Later, if you want to make an update to this addon in the collection, you
can make a PUT request to the addon URL:
    $ curl -sD - -u "$USER:$PASSWD" -XPUT \
        -d 'comments=This+addon+is+really+swell' \
        'http://dev-bandwagon.addons.mozilla.org/en-US/firefox/api/1.3/sharing/collections/109/addons/farming%40microfarmer.org'
   
    HTTP/1.1 200 OK
    Date: Fri, 20 Feb 2009 00:10:32 GMT
    Server: Apache/2.2.8 (Unix) mod_ssl/2.2.8 OpenSSL/0.9.7l DAV/2 PHP/5.2.6
    X-Powered-By: PHP/5.2.6
    X-AMO-ServedBy: quadshot-2.local
    Cache-Control: public, max-age=3600
    Last-modified: Fri, 20 Feb 2009 00:10:32 GMT
    Expires: Fri, 20 Feb 2009 01:10:32 GMT
    Transfer-Encoding: chunked
    Content-Type: text/xml
       
    <?xml version="1.0" encoding="utf-8" ?>
    <addon xml:base="http://dev-bandwagon.addons.mozilla.org/en-US/firefox/api/1.3/sharing/collections/109/addons/farming%40microfarmer.org">
        <meta>
            <added>2009-02-19T17:10:50-05:00</added>
            <addedby>Sancus</addedby>
            <comments>This addon is really swell</comments>
            <collection href=".." />   
        </meta>
        <categories>
            <category id="12">Organizer</category>
            <category id="13">Web Data</category>
        </categories>
        <name>MicroFarmer</name>
        <type id='1'>Extension</type>
        <guid>farming@microfarmer.org</guid>
        <version>9</version>
        <!-- details omitted... -->
    </addon>
==== Deleting an addon from a collection ====
Finally, if you want to remove this addon from the collection, make a DELETE
request to the addon URL:
    $ curl -sD - -u "$USER:$PASSWD" -XDELETE \
        'http://dev-bandwagon.addons.mozilla.org/en-US/firefox/api/1.3/sharing/collections/129/addons/farming%40microfarmer.org'
   
    HTTP/1.1 410 Gone
    Date: Fri, 20 Feb 2009 00:12:18 GMT
    Server: Apache/2.2.8 (Unix) mod_ssl/2.2.8 OpenSSL/0.9.7l DAV/2 PHP/5.2.6
    X-Powered-By: PHP/5.2.6
    X-AMO-ServedBy: quadshot-2.local
    Content-Length: 0
    Content-Type: text/html
   
The addon URL can no longer be found:
    $ curl -sD - -u "$USER:$PASSWD" -XGET \
        'http://dev-bandwagon.addons.mozilla.org/en-US/firefox/api/1.3/sharing/collections/109/addons/farming%40microfarmer.org'
   
    HTTP/1.1 404 Not Found
    Date: Fri, 20 Feb 2009 00:12:57 GMT
    Server: Apache/2.2.8 (Unix) mod_ssl/2.2.8 OpenSSL/0.9.7l DAV/2 PHP/5.2.6
    X-Powered-By: PHP/5.2.6
    X-AMO-ServedBy: quadshot-2.local
    Cache-Control: public, max-age=3600
    Last-modified: Fri, 20 Feb 2009 00:12:58 GMT
    Expires: Fri, 20 Feb 2009 01:12:58 GMT
    Content-Length: 120
    Content-Type: text/xml
   
    <?xml version="1.0" encoding="utf-8" ?>
    <error xmlns="http://addons.mozilla.org/" reason="addon_not_in_collection" />
And, the addon no longer appears in the collection:
    $ curl -sD - -u "$USER:$PASSWD" -XGET \
        'http://dev-bandwagon.addons.mozilla.org/en-US/firefox/api/1.3/sharing/collections/109/'
   
    HTTP/1.1 200 OK
    Date: Fri, 20 Feb 2009 00:13:55 GMT
    Server: Apache/2.2.8 (Unix) mod_ssl/2.2.8 OpenSSL/0.9.7l DAV/2 PHP/5.2.6
    X-Powered-By: PHP/5.2.6
    X-AMO-ServedBy: quadshot-2.local
    Cache-Control: public, max-age=3600
    Last-modified: Fri, 20 Feb 2009 00:13:55 GMT
    Expires: Fri, 20 Feb 2009 01:13:55 GMT
    Content-Length: 440
    Content-Type: text/xml
   
    <?xml version="1.0" encoding="utf-8" ?>
    <collection xmlns="http://addons.mozilla.org/"
        xml:base="http://dev-bandwagon.addons.mozilla.org/en-US/firefox/api/1.3/sharing/collections/109/"
        name="Foo Bar"
        description="collection of foobar addons"
        creator="Sancus"
        listed="yes" writable="yes" subscribed="no"
        lastmodified="2009-02-19T19:05:55-05:00">
   
        <addons href="addons/">
           
        </addons>
   
    </collection>
LesOrchard
Confirmed users
920

edits

Retrieved from "https://wiki.allizom.org/Special:MobileDiff/127515...137396"