Searching for add-ons using JSON
/rest/2/addons API lets you query add-on listings. You may wish to use this, for instance, to write a script that outputs information about every add-on that meets some criteria.
For an example of such a script (using the Bash shell and
list-addons.sh in the Marketplace API Tutorials repository.
You will need:
Step 1: Getting the resource URL
The base URL for the add-on collection resource is currently
https://marketplace.atlassian.com/rest/2/addons (with optional query parameters as described below).
Rather than hard-coding the URL path for the resource, you can also obtain it by starting from the entry point of the API. This takes additional steps, but is a better practice in case resource paths ever change in the future.
— you will receive a JSON response that looks something like this:
addonsprovides the URL path for the add-on collection resource.
Step 2: Optional query parameters
The following optional parameters can be used to filter and/or sort your search query:
||Only returns add-ons compatible with the specified application|
||Only returns add-ons compatible with the specified application build number;
Only returns add-ons with the specified categories;
||Only returns add-ons with the specified paid/free status|
||Return add-ons filtered or sorted using the specified parameter|
||Only returns add-ons from vendors associated with the current user; you have to be authenticated to use this|
||Only returns add-ons with the specified hosting model|
||Includes add-ons that are normally hidden in the site; default value is
||Includes private add-ons if you are authorized to see them (you have to be authenticated to use this); default value is
||Only returns add-ons that match the search text|
|Includes the latest compatible add-on version in the response (it will be in
limit parameters are used for pagination to limit the number of add-ons returned by the search query.
Rather than referring to this table, you can get the list of supported parameters directly from the API:
- Do a GET request to the add-on collection resource, adding
?limit=0to indicate that you don't want any add-on data but only the links:
In the JSON response, look for the
templatedproperty for this link indicates that it is a link template; in its
hrefvalue, the symbols within curly braces indicate all the optional query parameters that you can use, using URI Template syntax.
Step 3: Performing the query
- HTTP method:
- URL: the add-on collection resource, as described above, along with any optional query parameters
- Authentication: if you want to see private or user-specific data (using
includePrivate), you must provide Basic Authentication with the username and password of your Atlassian Account
Example of a curl request to get free add-ons that are compatible with JIRA:
/_links/alternate: A web link for viewing the corresponding list of results on the Marketplace site.
/_links/next: This will only be present if there are additional pages of results available after this one (the default size of a page is 10, unless you specify otherwise using
limit). Note that is not a single link, but an array of two links: the first is a resource link for getting the next page via REST (content type "application/json"), and the second is a web link for displaying the next page of results on the Marketplace site (like the
/embedded/addons: An array containing the add-on items. Note that these do not contain all properties of each add-on, but only a subset of the properties; to view all the properties, you can query the individual add-on resource using the
selflink for that item.
/count: the total number of results matched by the query, even if it is more than will fit in a single result page.