User:Clouserw/AMO/SharingAPI
|
THIS PAGE IS A WORKING DRAFT | 
|
| The page may be difficult to navigate, and some information on its subject might be incomplete and/or evolving rapidly. If you have any questions or ideas, please add them as a new topic on the discussion page. |
This is a discussion/planning. Please feel free to edit or ask questions.
Update: Looks like none of this will be happening. Details here if you have access and public announcements coming soon. More info ask clouserw or gkoberger.
The sharing API is one of the last strongholds of PHP on AMO and we need to move it to python. It's used by the Add-on Collector extension. This was originally implemented as a RESTful API and has extensive documentation. The PHP code starts here. The extensions use API version 1.3 so we can implement this on >=1.5 with no concerns.
There are currently 6 used URLs (read the docs for what they do):
> /api/[\d\.]*/sharing/collections/*/addons/ > /api/[\d\.]*/sharing/collections/* > /api/[\d\.]*/sharing/auth > /api/[\d\.]*/sharing/auth/* > /api/[\d\.]*/sharing/email > /api/[\d\.]*/sharing/
Now is a great opportunity to:
- Leverage django-piston which is already a part of AMO to reuse code where we can and to get all the REST benefits it provides
- Re-do the URL structure to move away from "sharing" and towards something more appropriate for whatever we are displaying (eg. /collection/ the same way we have /addon/)
I've got open questions and ideas below. Please give feedback - I have relatively little experience with the whole thing.
- [open] How RESTful do we have to be? How RESTful do we want to be? A lot of the current code has discoverability in it (lots of hrefs) which is great but may not translate to being a part of the public API.
> /api/[\d\.]*/sharing/collections/*/addons/
- This has a <meta> and a <categories> tag at the top but otherwise appears very similar to an old version of our public api. Example: https://services.addons.mozilla.org/en-US/firefox/api/1.5/addon/1865 vs https://addons.mozilla.org/en-US/firefox/api/1.5/sharing/collections/a7fcd566-1b16-5937-7d7d-d13315a94965/addons/%7Bd10d0bf8-f5b5-c8b4-a8b2-2b9879e08c5d%7D/ (you'll need auth for that second link, but if you add adblock plus to your own collection you can see what I'm talking about).
- [open]: If we add <categories> always and <meta> if you are authenticated to the current public API, can we just use the alternative URL?
- [open]: <meta> doesn't really make sense in the public API's context. Can we give it a better name or hierarchy?
> /api/[\d\.]*/sharing/collections/*
- This feels like it could be a public API at just /api/1.x/collection/$guid/. We could add the <links> tag (which holds CRUD urls) if the user is authenticated.
> /api/[\d\.]*/sharing/auth > /api/[\d\.]*/sharing/auth/*
- [open] I'm hoping piston can fix us up here. It already handles basic auth it looks like - does it contain the ability to create/delete sessions?
- [open] Additionally, how does browserid affect what we do here? We'll either need to use browserid in the add-ons or generate keys on AMO and somehow get those to the users (piston has oauth, but ugh).
> /api/[\d\.]*/sharing/email
- This simply sends emails to users. This can be a straight port to python I think, even at the same URL.
> /api/[\d\.]*/sharing/
This is the service document for the whole API. I think we could move this to /api/1.x/user/:username/collections/. Thoughts on that?
- We could either require authentication for it or show public collections by default and show private collections as well if they are authed. Have to be careful about caching on that but could be done.
- [open]: By default the public API has no auth and by default the sharing API does. Open to ideas on the best way to migrate those.
- Idea: If you are unauthenticated and request a private /collection/ URL, you are prompted for basic auth (much as you are today). This would reveal if collections existed or not but not what was in them. I don't think that's a problem.
