MozillaWiki

User:LesOrchard/BandwagonAPI: Difference between revisions

User page Discussion

User:LesOrchard/BandwagonAPI (view source)

Revision as of 23:27, 19 February 2009

10,413 bytes added ,  19 February 2009
no edit summary
No edit summary
No edit summary
Line 1: Line 1:
== Bandwagon API ==
== Bandwagon API ==
=== Open Questions ===
* 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)
*** 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)


=== Implementation Notes ===
=== Implementation Notes ===
Line 99: Line 93:
The URL paths used as headers are conceptual examples, not intended for  
The URL paths used as headers are conceptual examples, not intended for  
literal use as templates in the client application.
literal use as templates in the client application.
Also note that not all HTTP methods are avalable for every resource.


==== Service Document - /api/sharing/ ====
==== Service Document - /api/sharing/ ====
Line 127: Line 123:
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 154: Line 155:
** Status: <tt>200 OK</tt>
** Status: <tt>200 OK</tt>
** Content-Type: [[#Addon Collection]]
** Content-Type: [[#Addon Collection]]
===== DELETE - Delete a collection =====
* Response (on success)
** Status: <tt>410 Gone</tt>
==== 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 =====
===== POST - Add an addon to a collection =====
Line 172: Line 187:
** Content-Type: [[#Error Document]]  
** Content-Type: [[#Error Document]]  


===== DELETE - Delete a collection =====
==== Addon in a Collection - /api/sharing/collections/{uuid}/addons/{addon guid} ====
 
* Response (on success)
** Status: <tt>410 Gone</tt>
 
==== 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.
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 =====
Note that the GET method is not currently implemented, because the parent
 
collection doc provides the information that would conceivably be made
* Response (on success)
available.
** Status: <tt>200 OK</tt>
** Content-Type: [[#Addon]]


===== PUT - Update addon details in a collection =====
===== PUT - Update addon details in a collection =====
Line 448: Line 456:
     </addon>
     </addon>


=== Examples ===
=== 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"


This API can be exercised using [http://curl.haxx.se/ cURL] at a command line:
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 come up with 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-19T17:02:37-05:00">
       
    </collection>
   
==== Adding an addon to a collection ====
 
Adding an addon to a collection is very similar to creating a collection:
 
    $ 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/'
   
    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 fetch 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>
   
Note that there's a <tt>collection</tt> element with an <tt>href</tt> attribute
pointing to the parent collection, when resolved using the <tt>xml:base</tt>
URL.
 
You can also fetch the collection again and see the addon has appeared:
 
    $ 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:13:34 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:13:34 GMT
    Expires: Thu, 19 Feb 2009 23:13:34 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-19T17:02:37-05:00">
       
        <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>
       
    </collection>
   
Note that there's an <tt>href</tt> attribute on the <tt>addon</tt> element
pointing to the addon, when resolved using the <tt>xml:base</tt>
URL.
 
=== Open Questions ===
 
* 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)
*** 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)
LesOrchard
Confirmed users
920

edits

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