User:Clouserw/AMO/API
We'll be using the django-piston library as a foundation so requests correspond to what piston defines.
- GET == READ
- POST == CREATE
- PUT == UPDATE
- DELETE == REMOVE
PUT and POST accept JSON and multipart JSON + Files (depending on the URL it's submitting to). All URLs should send Accept: application/json headers.
- OPTIONS
- If we have the opportunity (and maybe piston already does this?) but every URL should return a list of what it can accept with OPTIONS.
open questions are in red
Contents
API Spec
- If a cell is blank, we return the appropriate HTTP error/NOOP
/api/addons
| GET | PUT | POST | DELETE |
|---|---|---|---|
| Creates a new add-on with provided data (multipart) |
/api/addon/:id
| GET | PUT | POST | DELETE |
|---|---|---|---|
| Display add-on details (done) | Update the add-on details | (In theory we should replace everything about the add-on, but that's a scary thought.) | Remove the add-on. (also scary) |
Add-on properties are listed below. They are split out so we can accept PUT for smaller chunks of data instead of overwriting the whole add-on, as above. All the URLs below accept GET/PUT/POST/DELETE/OPTIONS.
Simple text fields (minimal validation)
- /api/addon/:id/properties/name
- /api/addon/:id/properties/slug
- /api/addon/:id/properties/summary
- /api/addon/:id/properties/description
- /api/addon/:id/properties/homepage
- /api/addon/:id/properties/default_locale
- /api/addon/:id/properties/support_email
- /api/addon/:id/properties/support_url
- /api/addon/:id/properties/developer_comments
- /api/addon/:id/properties/tags
- /api/addon/:id/properties/eula
- /api/addon/:id/properties/privacy_policy
Accepts key/values: Name, URL, text (or should we split this up?)
- /api/addon/:id/properties/license
User will need to GET /api/categories for a list of available category ids before POSTing here
- /api/addon/:id/properties/categories
This accepts 2 text fields, one for URL, one for product
- /api/addon/:id/properties/getsatisfaction
This accepts a single binary file
- /api/addon/:id/properties/icon
This accepts multiple images/videos (maybe just single for starters). We'll also need /api/addon/:id/image/:id for GET
- /api/addon/:id/images
- /api/addon/:id/videos
This accepts some form of a list of add-on ids
- /api/addon/:id/properties/required_addons
This accepts a key/value pair of flags (or should we split this out into .../flags/$flag?). There are about 4 or 5 of them
- /api/addon/:id/properties/flags
This is GET only
- /api/addon/:id/properties/guid
- /api/addon/:id/authors and /api/addon/:id/author/:id
This accepts a key/value: permission level and a boolean for whether the user is listed. What should ?? be? The author's email addresss? If so, we could accept PUT directly to a URL.
- /api/addon/:id/authors/??/permission
/api/addon/:id/versions
| GET | PUT | POST | DELETE |
|---|---|---|---|
| Creates a new version. 301s to version detail page. |
/api/addon/:id/version/:id
| GET | PUT | POST | DELETE |
|---|---|---|---|
| Returns version details | Updates the version details+file | Replaces the version details+file | Removes the version |
Simple text field
- /api/addon/:id/versions/:id/release_notes
multipart: Accepts a single binary file, with a little metadata blob (platform, etc.)
- /api/addon/:id/versions/:id/files
Accepts a blob of app+version compatibility. Clients will have to GET */api/???? first
- /api/addon/:id/versions/:id/compatibility
/api/addon/builder
| GET | PUT | POST | DELETE |
|---|---|---|---|
| Returns an .xpi file from submitted data. |
/api/addon/validate
| GET | PUT | POST | DELETE |
|---|---|---|---|
| Validates the uploaded file and returns the results. |
- TODO: Contributions stuff (backend isn't determined yet)
- Acknowledge HATEOAS
Notes
Offline Processing
We'll handle offline processing by exposing the queue via the API and UUIDs. An example is probably the best explanation:
- POST /api/addons
- Server responds with a 202 Accepted and Location: /api/queue/:uuid (uuid is a random queue identifier)
- User follows redirect, receives 200 OK until the processing has completed. The body of this response can have details about the progress if available.
- If the processing was successful: 301 Found and Location: :url
- If the processing was not successful: 400 Bad Request and the body will contain details about what went wrong
Job tickets are GCd after 2 weeks.
