By using this website you implicitly accept our cookies. For more informations read our Cookie policy

Index

Introduction

The Marketcloud API follows the REST architectural guidelines and uses standard HTTP response codes to indicate the result of each operation.

If you want to dive into the api, visit the Getting started section, this document will present some conventions used in our api.

Table of contents

  1. Api version
  2. Root endpoint
  3. Secure connections
  4. Sending and receiving data
  5. Authentication and authorization
  6. Allowed HTTP methods
  7. Server responses
  8. Pagination
  9. Sorting

API version

The current version of the API is the v0 but this will change in the future since new versions will be released. To ensure the stability of your application built on Marketcloud, we prepend the api version to each endpoint of the API, so you can always decide which version of the api to use.

Root endpoint

You can send a GET request to the root endpoint of the api https://api.marketcloud.it/v0 to get the available resources for that api version. You will also find links to the documentation. .

Secure connections

HTTPS is required. We provide a valid, signed certificate for all API endpoints. API wrappers are required to use HTTPS too.

Sending and receiving data

All api endpoints are accessed through HTTPS and the base url is https://api.marketcloud.it/{version}. All data is received and sent as JSON. It is a common, simple and well known format for data exchange. There are good parsers and it is very usable in web applications.

We wrap JSON responses in a common format. At the root of the response object we always have the status flag, which is a boolean representing the result of the operation. It reflects the HTTP status code returned, HTTP codes >= 400 turn this flag to false. The data object is always present, except for DELETE requests, and it contains a list of resources or a single resource.


// curl https://api.marketcloud.it/v0/products          
{
  status : true,
  data : [...]
}                 
// curl https://api.marketcloud.it/v0/products/1234            
{
  status : true,
  data : {...}
}              
            

Authentication and Authorization

All API requests must provide credentials in the Authorization header, otherwise will be rejected with a 401 response code. Depending on the provided credentials, the client will have different authorizations, for example, providing just the public key will only allow "public" actions. Learn more about authentication here.

Errors

HTTPS is required. We provide a valid, signed certificate for all API endpoints. API wrappers are required to use HTTPS too.

Allowed HTTP methods

Method Description
GET Gets a resource or list of resources
POST Creates a resource
PUT Updates a resource
DELETE Deletes a resource

Server responses

Code Name Description
200 OK The request was successful.
400 Bad Request The request could not be understood or was missing required parameters.
401 Unauthorized Authentication failed or user doesn’t have permissions for requested operation.
404 Not Found Resource not found.
405 Method Not Allowed Requested method is not supported for resource.
500 Internal Server Error Something went wrong during your request

Pagination

Requests returning a list of items will be paginated to 20 items by default. You can require a different number of item per page using the GET parameter per_page and you can get a specific range of items combining it with the GET parameter page.

The following request will ask for 30 products, skipping the first 60 items.

curl 'https://api.marketcloud.it/v0/products?per_page=30&page=3

Sorting

Requests returning a list of items will be sorted by id in descending order by default. You can change the sorting behaviour with GET parameters sort_by and sort_order.

The following request will products by name in a descending order.

curl 'https://api.marketcloud.it/v0/products?sort_by=name

The following request will products by price in a ascending order.

curl 'https://api.marketcloud.it/v0/products?sort_by=price&sort_order=ASC

Questions?

We're super happy to help with any question you might have! Send us an email, or get in touch with us in our Slack channel !