Products
/
Mirakl Platform
/
GraphQL Reference
/
General Notes

GraphQL Reference

GraphQL API is designed to facilitate seamless interactions between the front-end operations of your Mirakl platforms and your backend systems. This documentation encapsulates essential features, including authentication, querying methods, pagination techniques, mutations, attachment management and a special focus on node queries for robust e-commerce management.

GraphQL endpoint

The GraphQL endpoint is accessible at /api/graphql on your Mirakl platform.

Authentication

Secure access to the GraphQL API is ensured through the use of a front API integration.

See our APIs Reference for more information on how to authenticate your requests.

GraphQL Schema and Queries

The GraphQL schema is self-documenting, offering insights into types, queries, mutations, and their interrelations.

Pagination

Our GraphQL API implements cursor-based pagination to allow clients to efficiently navigate large collections of data. This approach provides precise control over data fetching and is well-suited for real-time applications with large datasets.

Arguments for Pagination

first: Int

  • Description: Fetches the first n elements from the list.
  • Type: Int
  • Usage: This argument is used when you want to retrieve the first n items from a collection. It is typically used for forward pagination.

Example:

{
  users(first: 5) {
    edges {
       node {
         id,
         name 
       }
    }
  }
}

after: String

  • Description: Fetches the elements in the list that come after the specified cursor.
  • Type: String
  • Usage: This argument is used in conjunction with first to get the next set of items in a list after a certain cursor position. The cursor is usually an opaque string, like an ID or a timestamp.

Example:

{
  users(first: 5, after: "cursor123") {
    edges {
       node {
         id,
         name 
       }
    }
  }
}

last: Int

  • Description: Fetches the last n elements from the list.
  • Type: Int
  • Usage: This argument is used when you want to retrieve the last n items from a collection. It is often used for backward pagination.

Example:

{
  users(last: 5) {
    edges {
       node {
         id,
         name 
       }
    }
  }
}

before: String

  • Description: Fetches the elements in the list that come before the specified cursor.
  • Type: String
  • Usage: Similar to after, but used for fetching items before a certain cursor, typically for backwards pagination.

Example:

{
  users(last: 5, before: "cursor321") {
    edges {
       node {
         id,
         name 
       }
    }
  }
}

How Cursor-Based Pagination Works

Each item in a collection is associated with a cursor. This cursor is an opaque string that represents a position in the dataset.

When querying a list, clients can specify first and/or after to get a slice of the list starting at a particular cursor. Similarly, they can specify last and/or before to get a slice ending at a particular cursor.

The API responds with the requested list of items and also provides cursors for clients to request subsequent or preceding data slices.

Queries

Standard queries

The GraphQL API provides a set of standard queries to retrieve data from the Mirakl platform. These queries are designed to facilitate common operations such as fetching orders, products, shops, and more.

Node Queries

Node queries are a cornerstone feature, allowing the retrieval of any data object by its unique ID across different types within our schema. This facilitates efficient and flexible data access, essential for dynamic e-commerce operations.

Usage: Provide the id argument (the unique identifier of the object) to fetch detailed information about an object, regardless of its type.

Example:

query ShopById($id: ID!) {
   node(id: $id) {
      id
      ... on Shop {
        name
        banner
        dateCreated
      }
   }
}

Mutations

Mutations are used to modify data on the Mirakl platform. They allow clients to create, update, or delete objects in the system. The GraphQL API provides a range of mutation operations to support various use cases, such as updating an order, posting a message to a thread...

File Management

In order to deal with file management, the following steps must be implemented:

  1. Upload a temporary file:
PUT /api/graphql/upload
Host: tenant-id.mirakl.net
Authorization: Bearer <your-bearer-token>
Content-Type: image/png
...

<file-content>
  1. An URL is generated with the file downloadable
200 OK
{
	"url": "https://tenant-id.mirakl.net/api/graphql/download/JAAAAAIAAAABAAAAAAAAOseK-4QkvyW7iNDaVdxH66sz07pmgCITLIS0vUHnpRDhUhTYEk4d6_8wlxlpYFJKxgVyWDS1pFVBNnxHVASWxp0gJmntncaEC2vkk8ZuvFKepeT-PP2uii3aFGdml_9mrOR_Ek1QvHJ2SPLVf1kaIlkx2j-hkl-E9LrOb_35Pd7vEsQfbG7Wjqi0XQ02zCjl9sAVynX1K1GqSavs9IxIL6oNfHWoWZGOs29QUmxJqNY5pCUNL96J831L-4n-LcGsdLkb0u1LlhEx4jhzhJxbjsIdLqoyw90nT-We86nq9XQNHTl39RTWjTmROzjsVtsRbqUlrL3MWwKepZrIZJDQbvAIRsKqdnNJztI08Xmk76tzcJ9beUs9WKS92_C3YRQScQUe5ilUtF53nPBtFxcQb1uKm10-b-pwIMbQqzeCX24acTMd58p1uTgMGwZlxUapAUt2rKdIzVvuN4I4FDathbHBHBAQGI0wG5T1rf5pS-IvGq9i5cWjKmfr2AMsB-E1Q1gpiF_Ygqd1TuPStxRdz825I98Clhw="
}

This url can be used in a mutation where an AttachmentInput.url is needed.

Example:

mutation CreateThread($orderId: ID!, $input: CreateThreadInput) {
	createThreadOnOrder(orderId: $orderId, input: $input) {
		id
	}
}

where $input is:

{
	"orderId": "b3JkZXItTUlSLUtaWkM2UVNPLUE",
	"input": {
		"attachments": [
			{
				"name": "test.png",
				"url": "https://tenant-id.mirakl.net/api/graphql/download/JAAAAAIAAAABAAAAAAAAOseK-4QkvyW7iNDaVdxH66sz07pmgCITLIS0vUHnpRDhUhTYEk4d6_8wlxlpYFJKxgVyWDS1pFVBNnxHVASWxp0gJmntncaEC2vkk8ZuvFKepeT-PP2uii3aFGdml_9mrOR_Ek1QvHJ2SPLVf1kaIlkx2j-hkl-E9LrOb_35Pd7vEsQfbG7Wjqi0XQ02zCjl9sAVynX1K1GqSavs9IxIL6oNfHWoWZGOs29QUmxJqNY5pCUNL96J831L-4n-LcGsdLkb0u1LlhEx4jhzhJxbjsIdLqoyw90nT-We86nq9XQNHTl39RTWjTmROzjsVtsRbqUlrL3MWwKepZrIZJDQbvAIRsKqdnNJztI08Xmk76tzcJ9beUs9WKS92_C3YRQScQUe5ilUtF53nPBtFxcQb1uKm10-b-pwIMbQqzeCX24acTMd58p1uTgMGwZlxUapAUt2rKdIzVvuN4I4FDathbHBHBAQGI0wG5T1rf5pS-IvGq9i5cWjKmfr2AMsB-E1Q1gpiF_Ygqd1TuPStxRdz825I98Clhw="
			}
		],
		"threadInput": {
			"body": "Hello world!",
			"to": [
				"SHOP",
				"OPERATOR"
			],
			"topic": {
				"type": "FREE_TEXT",
				"value": "Hello"
			}
		}
	}
}

Rate Limiting Policy

To maintain optimal performance and equitable access, our GraphQL API features a rate limiting policy designed to prevent excessive resource consumption by any single user or client. This ensures a reliable service for all users.

Understanding Rate Limits

Rate limits in our GraphQL API are determined by the complexity of your queries and the frequency of your requests. Each query incurs a "cost," with restrictions on the total cost allowed within specified timeframes (minute, hour, day).

Cost Calculation

The cost of a query is influenced by its base weight and any applicable slicing arguments, which can increase the cost based on the number of sub-elements retrieved. Our system calculates the cost dynamically, ensuring fair usage based on the resources each query consumes.

Example Query Explanation

Using the threads query as an example:

threads(
    customerId: ID,
    first: Int @paginationLimit(default: 10, max: 100),
    after: String,
    last: Int @paginationLimit(max: 100),
    before: String
): ThreadConnection! @cost(weight: 1, slicingArguments: ["first", "last"])
  • Base cost is 1.
  • Slicing arguments like first or last affect the total cost when retrieving items such as messages in each thread.
  • If messages are included in the request, the cost is 1 + (n * 1), where n is the count determined by slicing arguments. The default value applies if no slicing argument is provided, i.e. 10 in this example.

Overages and Restrictions

Exceeding your allocated cost leads to temporary restrictions. Repeated overages trigger a review and potential outreach for query optimization.

With a state-of-the-art integration, the limits are sufficiently high to allow you to manage your front office displays without reaching them.

Query Complexity Guidelines

  • Simplify Queries: Aim for the least complex query that satisfies your data needs. This is the essence of GraphQL!
  • Consolidate Requests: Reduce the number of server calls by grouping data requirements.
  • Stay Informed: Monitor your usage closely to avoid hitting your limits unexpectedly.

Reach out to our support team if you encounter rate limit issues.

This policy is essential for sustaining high service quality for all users. Your understanding and cooperation are greatly appreciated.