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.
- 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
- If a cell is blank, we return the appropriate HTTP error/NOOP
|Creates a new add-on with provided data (multipart)|
|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)
Accepts key/values: Name, URL, text (or should we split this up?)
User will need to GET /api/categories for a list of available category ids before POSTing here
This accepts 2 text fields, one for URL, one for product
This accepts a single binary file
This accepts multiple images/videos (maybe just single for starters). We'll also need /api/addon/:id/image/:id for GET
This accepts some form of a list of add-on ids
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
This is GET only
- /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.
|Creates a new version. 301s to version detail page.|
|Returns version details||Updates the version details+file||Replaces the version details+file||Removes the version|
Simple text field
multipart: Accepts a single binary file, with a little metadata blob (platform, etc.)
Accepts a blob of app+version compatibility. Clients will have to GET */api/???? first
|Returns an .xpi file from submitted data.|
|Validates the uploaded file and returns the results.|
- TODO: Contributions stuff (backend isn't determined yet)
- Acknowledge HATEOAS
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.