-
Notifications
You must be signed in to change notification settings - Fork 279
Extension Repository Server API
Server API requirements to support the workflows.
- A REST+JSON API
- Focused on use within Brackets
- There may be a web-facing interface of some sort later
- Clients other than Brackets/Edge Code are not important
- Consequently, level 2 on the Richardson Maturity Model is likely about right
- Everything a user needs to be able to find and install extensions should be available without authentication
- Authenticated APIs must use https
- Server certificate should be verified to avoid man in the middle attacks (in other words, don't turn this feature off)
- Provides everything the Extension Manager needs to display the list of extensions
- Fields needed:
- ID of extension (used for constructing download URL, for example)
- display name of extension
- date of last update
- download count (possibly total and "recent" (last week, perhaps) to help with sorting)
- version number
- a short description
- rating
- thumbnail URL (if available)
- homepage URL
- support URL
- a flag for "has been disabled"
- if an installed extension is marked "has been disabled", then it will be turned off automatically
- unauthenticated
- Downloads the extension package
- unauthenticated
- Allows the user to retrieve more detailed information about an extension
- Fields needed:
- Long description
- URLs for additional screenshots if any
- changelog
- Ratings breakdown
- Reviews
- unauthenticated
- Submits a rating (and possibly review) for a an extension
- Replaces a previous rating/review by the same user if there was one
- authenticated
- Used to report that an extension is malicious
- User can provide comments with further detail about the abuse
- Will send email to the Brackets team
- Sets the state to "pending disable"
- extensions that are "pending disable" do not appear in listings
- "pending disable" does not set the "has been disabled" flag in the listings
- someone from the Brackets team will investigate and change the state to disabled if they determine the extension causes harm
- "disabled" extensions are turned off on end user computers automatically
- authenticated
These notes were to help think through the API requirements. They may or may not reflect the desired approach once implementation starts.
The overall idea is a typical REST+JSON approach.
list is called once per day (or when the user forces a refresh) by Brackets. It provides a list of extensions with all of the data needed to provide:
- update notifications
- listings for the Find tab of the Extension Manager
There may come a time when this is too much data for the client to request every day. With the data gzipped, however, we can go for some time before this would be an issue.
Output example:
[
{
"name": "HoverPreview",
"title": "Hover Preview",
"description": "Shows a preview when the cursor is hovered over certain items",
"version": "0.4",
"screenshot": "http://s3.aws.blah.blah/8675309jennyabcdef",
"rating": 4.5,
"downloadsAll": 352122,
"downloadsRecent": 1021
},
{
"name": "html-templates",
"title": "HTML Templates",
"description": "Insert a chosen HTML template into the current file",
"version": "1.2",
"rating": 4.0,
"downloadsAll": 121211,
"downloadsRecent": 522
}
]Downloads the package for the latest version of the named extension. (See package format for details about the response.)
Retrieves detailed info about the extension.
{
"name": "HoverPreview",
"title": "Hover Preview",
"description": "Shows a preview when the cursor is hovered over certain items",
"longDescription": "Long, *markdownable* description...",
"version": "0.4",
"screenshot": "http://s3.aws.blah.blah/8675309jennyabcdef",
"moreScreenshots": ["http://url". "http://anotherurl"]
"rating": 4.5,
"ratingDetail": [20, 1, 3, 150, 225]
"downloadsAll": 352122,
"downloadsRecent": 1021,
"reviews": [
{
"rating": 4,
"title": "Finally!",
"review": "I've been waiting for this day for the past 25 years."
}
],
"homepage": "https://github.com/gruehle/HoverPreview",
"support": "https://github.com/gruehle/HoverPreview/issues",
"recentChanges": [
{
"version": "0.4",
"description": "Less soup."
},
{
"version": "0.3",
"description": "Rockets? Yeah, it's got rockets."
}
]
}All access to authenticated APIs will be via HTTPS.
Access to the APIs in this section require the user to be logged in.
Ideally, users will be able to use existing logins rather than learning a new password (GitHub, Twitter, Facebook, Google), but starting with a username/password is reasonable. Note: Passport may be one implementation strategy.
As far as authentication goes, we can start as simple as basic auth and move onward to oauth ourselves (user authorizes the copy of Brackets and a token is sent that is kept by the client). oauth "scopes" would provide a standardized mechanism for us to authorize clients to rate/review extensions without the ability to upload extensions. oauth is not the only way to do this, but it is a standard.
Logs a review for the given extension. If the user has already posted a review for this extension, it is replaced with the new one. The POST body is a JSON object with the review information. Example:
{
"rating": 4,
"title": "Fish!",
"review": "It ate my fish. I didn't like that fish anyway, though."
}rating is a required integer from 1 to 5. title is an optional review title and review is the optional review text. A review can include only a rating and title, but if review is present, title must be present, too.