Introduction

GraphQL is a query language for APIs. It lets you request only the data that you need. The Bonx GraphQL API gives you access to the data in your space: orders, receivings, shipments, articles, stock, production, quality, invoices, custom tables, and custom fields.

When should you use GraphQL?

Use GraphQL to read several related records in one request. For example, you can get a receiving, its lines, and the article for each line in the same request. For most integrations and for data changes, use the REST API. GraphQL is intended for advanced read operations. One exception lets you attach a document to a record.

Principles

One URL: Send all requests with POST to the GraphQL URL for your space.
A targeted response: List the fields that you want to receive.
An inspectable schema: Compatible tools can read the schema and suggest available fields, including your custom fields.

Authentication

Each request must contain an API token in the x-api-key header. See Authentication to create this token. The GraphQL URL for your space is provided with the token. The examples use the $BONX_GRAPHQL_URL and $BONX_API_KEY variables.

curl -X POST "$BONX_GRAPHQL_URL" \
  -H "x-api-key: $BONX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ receivings(limit: 1) { id name } }"}'

A token gives access to the data in your space. Never add it to code that runs in a browser. Revoke it immediately if it is exposed.

Request structure

Send a JSON object with a query key. Add a variables key if the query uses dynamic values.

{
  "query": "query GetReceiving($id: Int!) { receivingsByPk(id: $id) { id name } }",
  "variables": { "id": 412 }
}

Use variables instead of inserting values directly into the query string.

Operation names

Action	Example
Read a list	`receivings`, `salesOrders`
Read a record by its ID	`receivingsByPk(id: 412)`
Create a record	`insertReceivingsOne(object: { … })`
Update a record	`updateReceivingsByPk(pkColumns: { id: 412 }, _set: { … })`
Count or calculate across records	`receivingsAggregate`

The token permissions determine the available operations. Each change made with a token appears in the record history and is attributed to that token.

Continue to the Quickstart to send your first request.

​When should you use GraphQL?

​Principles

​Authentication

​Request structure

​Operation names

When should you use GraphQL?

Principles

Authentication

Request structure

Operation names