All API requests and response bodies adhere to a common JSON format representing individual items,
collections of items, links to related items and additional metadata.
Request Body and Response
All POST / PUT requests are expected to have a
root element object called data, where the client is expected to put the desired
payload, usually representing a resource to be created.
{
"data": {
... rest of the payload, usually representing a resource.
}
}
Similarly, all successful responses will always have a root data
object containing the response in question. The object contained should describe either a
single resource or a collection of resources.
Single Resource
Individual resources are always represented by an object identified with a
type
and
id
attributes, along with an
attributes
object containing the rest of the data.
This structure is expected within the body of a POST /
PUT request, and is also the structure returned by endpoints that
deal with a single resource.
The id attribute in particular is not expected within
POST requests since the resource in question is just being created.
{
"type": "segment",
"id": "123",
"attributes": {
"name": ...,
"total_brands": ...,
}
}
Resource Collection
Collections of resources are represented as an array inside the previously
mentioned data object. Each object inside the collection is expected to
have at least the type and id attributes.
{
"data": [
{
"id": "us/B088WVF1V1",
"type": "product_database_result",
"attributes": {
"title": "Product Title 1",
"price": 22.99,
}
},
{
"id": "us/B075YT5K59",
"type": "product_database_result",
"attributes": {
"title": "Product Title 2",
"price": 42.49,
}
}
]
}
Links
Single and collection results may provide a links object, which contain
references to a related resource (single resource result) or to the next page (collection result).
The following snippet depicts an example of a collection response containing a link to itself and
another one to fetch the next piece of data. Take a look at the
pagination section for more details
on the links[next] attribute.
{
"data": [ ...omitted for brevity ],
"meta": { ...omitted for brevity },
"links": {
"self": "https://developer.junglescout.com/api/product_database_query?marketplace=us",
"next": "https://developer.junglescout.com/api/product_database_query?marketplace=us&page%5Bcursor%5D=eyJwYWdpbmF0ZV9mcm9tIjo1MCwicGFnZV9zaXplIjo1MH0%3D%0A"
}
}
Meta
Some responses contain data that might not be directly related to the resources themselves.
In those cases, a meta attribute object is returned.
As of now, the main usage for this object is to report the
amount of total_items available in a collection response.
{
"data": [ ...omitted for brevity ],
"links": { ...omitted for brevity },
"meta": {
"total_items": 1200
}
}