API best practices
- Reduce duplicate calls to API requests.
- Restrict access tokens to specific IP addresses from which API calls are made.
- Regularly delete unused access tokens in the administration.
- Use public domain name in URL and correct protocol for API calls. This will prevent unnecessary HTTP redirection.
Instead of https://your-page.flox.cz/api/graphql, use
https://www.your-domain.cz/api/graphql - To restrict access to API functions, assign the token to users with limited rights.
- For regular updates, ask only for the data you really require. Enter in the query an exact list of parameters that are included in the answer for further processing or use notation using a custom fragment (see example no. 1).
- You can combine predefined fragments with a specific enumeration of other parameters.
- Divide complex or extensive queries into separate sub-queries and process requests one after the other. For example, if you require a complete structure of e-shop categories and product data at the same time. Process categories and products separately.
- Use smaller values for pagination (set the limit parameter to less than 30) when scrolling through lists and complex response structure. This applies to the methods getProductList, getOrderList, getInvoiceList, etc. if you also require linked data at deeper levels.
- When performing a mutation, it is advisable to include the currently changed parameters in the answer. At the same time, you will check that the operation was carried out correctly. For example, when changing the status of an order, it is advisable to immediately ask about its status in the reply (see example no. 2)
Examples:
1. Definition of a custom fragment sent along with the query
query {
getOrderList(lang_code: "SK", params: { order_by: pur_date, sort:DESC, limit:30, cursor:0}) {
pageInfo{
... _PageInfo
}
data{
... MyOrderData # using your own fragment
}
}
}
# custom fragment definition for specific order data
fragment MyOrderData on Order {
order_num
pur_date
sum {
formatted
}
}
HTTP payload and query
POST /api/graphql HTTP/1.1
Host: yourwebsite.com
BW-API-Key: Token Ijw..................gKsB7
Content-Type: application/json
Cookie: SSID=27s5cke5yr78c441203a01bbur
Content-Length: 500
{"query":"query {\r\n getOrderList(lang_code: \"SK\", params: { order_by: pur_date, sort:DESC, limit:30, cursor:0}) {\r\n pageInfo{\r\n ... _PageInfo\r\n }\r\n data{\r\n ... MyOrderData # using your own fragment\r\n }\r\n }\r\n}\r\n# custom fragment definition for specific order data\r\nfragment MyOrderData on Order {\r\n order_num\r\n pur_date\r\n sum {\r\n formatted\r\n }\r\n}","variables":{}}
2. Order status change. The response contains the changed parameters
mutation {
changeOrderStatus(order_num: "2302120", status_id: 4){
#request the changed parameters in mutation response
order_num
status {
id
name
}
}
}
HTTP payload and query
POST /api/graphql HTTP/1.1
Host: yourwebsite.com
BW-API-Key: Token Ijw..................gKsB7
Content-Type: application/json
Cookie: SSID=27s5cke5yr78c441203a01bbur
Content-Length: 281
{"query":"mutation {\r\n changeOrderStatus(order_num: \"2302120\", status_id: 4){\r\n #request the changed parameters in mutation response\r\n order_num\r\n status {\r\n id\r\n name\r\n }\r\n }\r\n}","variables":{}}
3. Writing a query using fragments and separate parameters
query {
getProduct(product_id: "26049"){
# fragment _Product contains "attribute_category" with only "id" and "title" params
... _Product
attribute_category {
id
title
# in the query you can override the parameter and spoecify different parameters
description
}
}
}
HTTP payload and query
POST /api/graphql HTTP/1.1
Host: yourwebsite.com
BW-API-Key: Token Ijw..................gKsB7
Content-Type: application/json
Cookie: SSID=27s5cke5yr78c441203a01bbur
Content-Length: 481
{"query":"query {\r\n getProduct(product_id: \"26049\"){\r\n # fragment _Product contains \"attribute_category\" with only \"id\" and \"title\" params\r\n ... _Product\r\n attribute_category {\r\n id\r\n title\r\n # in the query you can override the parameter and specify different parameters\r\n description\r\n }\r\n }\r\n}","variables":{}}