400996 - Developer documentation for the AMO API

Status: VERIFIED FIXED

(addons.mozilla.org Graveyard :: API, defect, P3)

Description

[Laura Thomson :laura]

The API will need some documentation, showing:
1.  API calls including params, param types, format of returned data (DTD?)
2.  Tutorial style docs.

The docs should be available on AMO.  They should be localizable and hence fit into the overall AMO framework.

Comment 1

[Fred Wenzel [:wenzel]]

Oh yes, /me votes for a DTD. People may want to do validation on their site.

Comment 2

[Basil Hashem [:baz]]

At some point, we'll also want to link to it from our MDC area

Comment 3

[Laura Thomson :laura]

I forgot to add here that draft version is available at
http://wiki.mozilla.org/Update:Remora_API_Docs

In the process of adding example return data and DTDs as per suggestions from Basil and others.

Comment 4

[Dave Townsend [:mossop] (PTO until Aug 21st)]

Other application developers are asking for more documentation on the API so they can develop their own services, can we increase the priority at all here?

Comment 5

[Basil Hashem [:baz]]

I'm going to create a dependency on bug 436307 (Create the Terms of Service (TOS) for AMO and the AMO API). We need some guidelines about how developers can use this part of AMO. The TOS outlines that and is currently being worked on by legal.

Comment 6

[Laura Thomson :laura]

I understand the ToS is being worked on at the moment (although bug 436307 is restricted to Legal).  Deferring again until that is done.

Comment 7

[Nick Nguyen [:osunick]]

ToS will go into this release, so no need to defer any longer.  We'll just need a link to the developer agreement in the doc, which I will provide once it's implemented.

Comment 8

[Nick Nguyen [:osunick]]

Deferring to 5.0.3, still waiting on legal for a revised TOS.

Comment 9

[Nick Nguyen [:osunick]]

Deferring again- talked to legal and this clearly isn't ready.  Going to put in a design bug for 5.0.4 to design the new flow and then target 5.0.5 for implementation.

Comment 10

[Nick Nguyen [:osunick]]

Laura, developer agreement is now up- is this feasible for 5.0.7

Comment 11

[Laura Thomson :laura]

Yep, should be good.

Comment 12

[Wil Clouser [:clouserw]]

Bandwagon: https://wiki.mozilla.org/User:LesOrchard/BandwagonAPI

Comment 13

[Wil Clouser [:clouserw]]

You said you'd have this done today so don't let me stop you ;), but I'd like to land it in 5.0.8 so QA can focus on the P1's for this release.  If you need a couple extra days, no worries, but let's land early in 5.0.8.

Comment 14

[Laura Thomson :laura]

I heard 5.0.7 was pushed out to Tuesday so I didn't stay up late to finish it :) I'm clear to work on it now anyway so shouldn't be long.

Comment 15

[Laura Thomson :laura]

I'm just about done...I was thinking of adding DTDs, are these wanted?

Also, where should the results go?  I know we talked about devmo at one point?

Comment 16

[Nick Nguyen [:osunick]]

DevMO is fine and we can link off Developer FAQ.

Comment 17

[Laura Thomson :laura]

Draft (complete I hope) at https://developer.mozilla.org/index.php?title=User:laurathomson/addons.mozilla.org_%28AMO%29_API_Developers%27_Guide

I'll move it up a level once you guys have had a chance to review.

Comment 18

[Wil Clouser [:clouserw]]

I think it looks great.  The search stuff will be outdated soon, but no worries.  The bandwagon stuff is awesome.

Comment 19

[Wil Clouser [:clouserw]]

Oh, I added a link to the dev agreement too.

Comment 20

[Laura Thomson :laura]

(In reply to comment #18)
> I think it looks great.  The search stuff will be outdated soon, but no
> worries.  The bandwagon stuff is awesome.

Credit Les for that, I wrote the generic part and just reformatted the (excellent) Bandwagon stuff he wrote for devmo.

Comment 21

[Laura Thomson :laura]

OK, I'll call this done - I haven't quite worked out how to move it though - Wil do you know?

Comment 22

[Eric Shepherd [:sheppy]]

Where do you want it? I can move it.

Comment 23

[Laura Thomson :laura]

Thanks Sheppy!  It should go up a level, ie not be under User:laurathomson.  The two leaf pages need to go as well.

Comment 24

[Eric Shepherd [:sheppy]]

I've moved it, and am doing a little tidy-up pass on it.

I just noticed in the description of the Search command that it says that "If no searchtype is entered extensions and themes will be returned" but down where it describes searchtype, it says that the default is "all". Which is correct?

Comment 25

[Laura Thomson :laura]

Aha, good catch.

If you do not specify the behavior is the same as if you specify 'all' - which is to return only extensions and themes, counterintuitive as that may be.

Comment 26

[Eric Shepherd [:sheppy]]

I've also added a link to this guide to the menu page here:

https://developer.mozilla.org/En/Developing_add-ons

Comment 27

[Eric Shepherd [:sheppy]]

OK, added an aside about the all thing. Going to be doing some more formatting tweaks to this over the rest of the afternoon, I think.

Comment 28

[Stephen Donner [:stephend] Not actively reading bugmail]

Looking really good up at https://developer.mozilla.org/en/addons.mozilla.org_%28AMO%29_API_Developers%27_Guide.

Verified FIXED.

Comment 29

[Eric Shepherd [:sheppy]]

I just finished a formatting cleanup and a few other little tweaks here (including clickable links to try out API requests):

https://developer.mozilla.org/en/addons.mozilla.org_%28AMO%29_API_Developers%27_Guide/The_generic_AMO_API

Going over the bandwagon doc next.