Getting app details using JSON

The app resource within the /rest/2/addons API lets you query app details, including every field that is visible in a Marketplace app listing or that can be set through Manage Listings.

For an example of a script that uses this (using the Bash shell and curl), see get-addons.sh in the Marketplace API Tutorials repository.

Prerequisites

You will need:

• Any tool for making HTTP requests
• The app key of an existing app

Step 1: Getting the resource URL

The URL for an app resource is currently https://marketplace.atlassian.com/rest/2/addons/ADDON_KEY - substituting your app key for ADDON_KEY.

However, 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.

1. Do a GET request to https://marketplace.atlassian.com/rest/2 — you will receive a JSON response that looks something like this:

   {
     "_links": {
       "self": {
         "href": "/rest/2"
       },
       [some more links...]
       "addons": {
         "href": "/rest/2/addons"
       }
     }
   }
   

2. The href property under addons is the URL path of the resource for finding apps. Do a GET request to this resource, with ?limit=0 added to indicate that you don’t actually want a full list of apps https://marketplace.atlassian.com/rest/2/addons?limit=0 — you will receive a JSON response like this:

   {
     "_links": {
       "self": {
         "href": "/rest/2/addons"
       }, [...some more links that you can ignore...]
       "byKey": {
         "href": "/rest/2/addons/{addonKey}",
         "templated": true
       }
     }
   }
   

3. Take the href property under byKey, and substitute the app key of your existing app for {addonKey} (for instance, /rest/2/addons/my.excellent.app). This gives you the URL path of the app resource.

Step 2: Optional query parameters

You may optionally add any of the same query parameters that are supported by a query for multiple apps, except for offset and limit which are not applicable to a single app. The usual reason for doing this would be to get the current version of the app (?withVersion=true) or to get the latest version that meets some criteria (?withVersion=true&cost=free&hosting=server).

Step 3: Performing the query

Request

• HTTP method: GET
• URL: the app resource, as described above, along with any optional query parameters
• Authentication: if you want to see private data, you must provide Basic Authentication with the username and password of your Atlassian Account

Here’s a sample curl request to get the details for my.excellent.app, along with the current version:

$ curl "https://marketplace.atlassian.com/rest/2/addons/my.excellent.app?withVersion=true"

Response

{
  "_links": {
    "self": {
      "href": "/rest/2/addons/my.excellent.app"
    },
    "alternate": {
      "href": "/plugins/my.excellent.app"
    }
  },
  "_embedded": {
    "logo": {
      "_links": {
        "image": "https://marketplace-cdn.atlassian.com/files/my.excellent.app/icons/default/e1692eef-eda8-4508-909a.png"
      }
    },
    "version": {
      "_links": {
        "href": "/rest/2/addons/my.excellent.app/build/100"
      },
      "buildNumber": "100",
      "name": "1.0.0",
      [...other version properties...]
    }
  },
  "key": "my.excellent.app",
  "name": "My Excellent App",
  [...other app properties...]
}

Response properties

• /_links/alternate: A web link for viewing the app details on the Marketplace site.
• /_embedded/logo/_links/image: An image URL for the app’s logo. Note that there is also a /_links/logo link, which you will not normally use.
• /_embedded/version: Information about the current (or latest matching) version of the app, if you specified withVersion=true.

There are many other app version properties and resource links; for details, see the REST API documentation.