API Standards
JSON API standards, content types, and implementation recommendations for the Stream API.
JSON API Standard
The Stream API follows the JSON API standard. This implies that all requests and responses are following the defined structure and are using the content-type application/vnd.api+json. Productsup does not accept the content-type set with the JSON API Standard to request bodies for product uploads. The reason for this is because:
- The
application/vnd.api+jsoncontent-type has too much overhead for product data - The
application/x-ndjsonoffers better performance when extracting single products from a request - The
application/jsonis our legacy standard, as Productsup does not want to force existing clients to change their entire integration
The non-acceptance does not imply that Productsup never supports sending
data in application/vnd.api+json format. However, there is a need to
understand the value first.
The product data upload endpoints are the only exception to the JSON API Standard.
Implementation recommendations
Compression support
Enable gzip compression with the following header:
Content-Encoding: gzipCurl option to enable gzip compression:
--header 'Content-Encoding: gzip'The Stream API supports gzip compression for product uploads to improve performance. Use the Content-Encoding header to specify gzip compression for request payloads. Gzip compression can significantly reduce the payload size, leading to shorter upload times and better performance.
See uploading data to learn how to use gzip compression with a product upload request with the two stream types.
Client header
We recommend using the User-Agent header to send additional information about your integration to the Stream API.
The default format of the User-Agent header looks as follows:
ProductName/Version (System Information) AdditionalDetails
ReactorNetty/1.1.23 Productsup/<INTEGRATION_NAME>
Go-http-client/2.0 Productsup/<INTEGRATION_NAME>
Java/21.0.3 Productsup/<INTEGRATION_NAME>
python-requests/2.31.0 Productsup/<INTEGRATION_NAME>We recommend adding the integration specific name in the
AdditionalDetails section of the User-Agent header. Use the format Productsup/<INTEGRATION_NAME>, where replace <INTEGRATION_NAME> with a desired name.
You can append the string to the AdditionalDetails section. See above for examples.
How is this guide?