Examples of API usage through JSON requests

The pages in this section illustrate how to perform some common Marketplace API operations by accessing the API directly and using JSON documents. For general characteristics and conventions of the API, please see [Marketplace API].

If you are writing a Java tool that integrates with Marketplace, it's more convenient to use the Marketplace API Java client instead; but if you are using a scripting language or some other tool, you will want to read these examples to become familiar with the low-level API details.

Tools for making HTTP requests

For these examples, you can use any tool that is designed for making HTTP requests to a web service. There are many such tools: browser plugins, such as Postman; standalone applications, such as the Windows rest-client; and command-line tools, such as the standard Linux command curl.

These examples do not require any specific tool, but we will provide Linux command-line examples using curl.

Referring to resource properties

Suppose that in one of the API examples, you have received a JSON document that looks like this:

1
2
{
  "_links": {
    "self": {
      "href": "/rest/2/resource"
    }
  },
  "name": "gold",
  "details": {
    "atomicNumber": 79
  }
}

We will use JSON Pointer syntax to describe the location of any property in this document:

  • /name - the top-level property called "name" (value is "gold")
  • /details/atomicNumber - the property "atomicNumber" within the property "details" (value is 79)
  • /_links/self/href - the property "href" within the property "self" within the property "links" (value is "/rest/2/resource")

If you are using a language such as JavaScript or Python where JSON documents are represented as native object/dictionary values, and your document is currently in a variable called doc, you can easily refer to a property like /_links/self/href using dot notation: doc._links.self.href.

Since the Marketplace API uses [HAL](https://en.wikipedia.org/wiki/Hypertext_Application_Language" class="external-link), resource links are always contained within a property called _links; so "the self link" is another way of referring to /_links/self.

Note that resource links are always relative to the server root, which is https://marketplace.atlassian.com. So, in this example, if we asked you to take the self link and do a GET request to it, you would actually be doing a request to https://marketplace.atlassian.com/rest/2/resource.

Rate this page: