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": "share_of_voice",
"id": "123",
"attributes": {
"product_count": ...,
"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
}
}
Breaking Change Policy
As our APIs evolve, we will make reasonable efforts to notify you of breaking changes in advance with sufficient time to adapt to these changes.
Important
We may make changes without prior notice if the change is considered non-breaking, or if it is a breaking change being made to address critical product bugs or legal, security, or privacy concerns.
Review this guide carefully to understand what kind of changes we consider to be breaking and non-breaking, and how to ensure that your integration can adapt automatically to any change we categorize as non-breaking.
A breaking change is a change that may require you to make changes to your integration in order to avoid disruption. The following are a few examples of changes we consider breaking:
- Changes to existing permission definitions
- Removal of an allowed parameter, request field or response field
- Addition of a required parameter or request field without default values
- Changes to the intended functionality of an endpoint. For example, if a DELETE request previously used to archive the resource but now hard deletes the resource.
- Introduction of a new validation
A non-breaking change is a change that you can adapt to at your own discretion and pace without disruption. In most cases, we will communicate non-breaking changes after they are already made. Ensure that your integration is designed to be able to handle the following types of non-breaking changes without prior notice:
- Addition of new endpoints
- Addition of new methods to existing endpoints
- Addition of new fields in the following scenarios:
- New fields in responses
- New optional request fields or parameters
- New required request fields that have default values
- Addition of a new value returned for an existing text field
- Changes to the order of fields returned within a response
- Addition of an optional request header
- Removal of redundant request header
- Changes to the length of data returned within a field
- Changes to the overall response size
- Changes to error messages
- Fixes to HTTP response codes and error codes from incorrect code to correct code
