If you want to exchange data with X-Cart through an external script, REST API is the way to go. This article explains how you can use X-Cart’s REST API.
Configuring REST API
To access X-Cart’s data externally, you must configure the REST API.
- Go to Settings > API in the admin area.
- On the setting page, define the values for the following fields:
- API key (read/write) - Add a key allowing an external application to have full access to X-Cart data (reading and writing);
- API key (only read) - Add a key allowing an external application to only read data.
Note: You can configure only one API key type if you prefer so.
For instance, we set the read/write key as “key-to-do-everything” and the read key as “key-for-reading.”
- To test REST API functionality, we are trying to perform the following request:
curl --location --request GET 'https://<X-CART-PATH>/api/products/1' \
--header 'Accept: application/json' \
--header 'X-Auth-Token: key-to-do-everything'
Be sure to replace the X-CART-PATH portion with the actual path to where your X-Cart is installed and the “key-to-do-everything” portion with your current REST API key.
- If a product with ID = 1 exists in your database, you will get a result similar to the following:
{
"og_meta_tags": "<meta property=\"og:title\" content=\"Timberland 45th Anniversary [Partner 2]\" />",
"market_price": 0,
"pin_codes_enabled": false,
"auto_pin_codes": false,
"participate_sale": false,
"discount_type": "sale_price",
"sale_price_value": 0,
"apply_sale_to_wholesale": false,
"available_for_backorder": false,
"backorder_limit": 0,
"cost_price": 0,
"stickers": [],
"facebook_marketing_enabled": true,
"google_feed_enabled": true,
"tags": [],
"id": 1,
"sku": "10000000065",
"name": "Timberland 45th Anniversary [Partner 2]",
"description": "",
"brief_description": "",
"meta_tags": "",
"meta_description": "",
"meta_title": "",
"price": 19.99,
"enabled": true,
"weight": 0.7,
"free_shipping": false,
"taxable": true,
"create_date": "2022-07-18T16:18:37+00:00",
"update_date": "2022-07-18T16:18:41+00:00",
"arrival_date": "2022-02-18T00:00:00+00:00",
"inventory_traceable": true,
"amount": 1000,
"product_class": null,
"tax_class": null,
"memberships": [],
"clean_url": "timberland-45th-anniversary",
"images": [
{
"id": 1,
"position": 10,
"alt": "",
"url": "http://dev.test/images/product/shoes_2.jpg",
"width": 366,
"height": 366
},
{
"id": 2,
"position": 11,
"alt": "",
"url": "http://dev.test/images/product/shoes_3.jpg",
"width": 366,
"height": 366
}
]
}
How do I work with data using REST API?
After configuring the REST API module, you can start receiving data from X-Cart. REST API allows to pull a particular entity identified by an ID, e.g., pulling a product with ID=1
curl --location --request GET 'https://<X-CART-PATH>/api/products/1' \
--header 'Accept: application/json' \
--header 'X-Auth-Token: key-to-do-everything'
or entities of a specific type, e.g., pulling all products
curl --location --request GET 'https://<X-CART-PATH>/api/products' \
--header 'Accept: application/json' \
--header 'X-Auth-Token: key-to-do-everything'
As you can see, in the first case, we passed the path as /api/products/1 (where 1 is the ID of a product we want to fetch), and in the second case, we passed it as /api/products (because we want to pull the info of all products).
Request parameters
Each REST API request must contain an X-Auth-Token HTTP header with a correct value.
In addition, you can pass the HTTP method that will define what you will do within this request. Here are the possible values:
- GET - if you want to pull data (it is the default value, no need to pass it). Pass an optional entity ID to get a specific entity.
- POST - if you want to create an entity. You must also pass a model params that will define the entity you are creating.
- PUT - if you want to change an entity. Requires to pass the entity ID in the endpoint. You must pass a model params in the body of your request that will define the changes you will apply to the entity.
- DELETE - if you want to remove an entity.
There is also an optional order param, which sets the search condition and allows you to filter and sort retrievable entities (it is suitable only for the GET method).
Localization
X-Cart REST API supports multiple languages, but all the requests are made in the same language. The language is set using the Accept-Language request in the HTTP header: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language.
If the header has not been sent, the default language as specified in the store settings is used.
Limiting the output (Pagination)
Pagination is enabled by default for all collections. Each collection contains 30 items per page by default.
You can change the number of items per page by adding a query parameter named itemsPerPage:
curl --location --request GET 'https://<X-CART-PATH>/api/products?itemsPerPage=10' \
--header 'Accept: application/json' \
--header 'X-Auth-Token: key-to-do-everything' \
The maximum number of items per page for all resources is 100.
To retrieve a specific page, use the page param in your request:
curl --location --request GET 'https://<X-CART-PATH>/api/products?itemsPerPage=10&page=2' \
--header 'Accept: application/json' \
--header 'X-Auth-Token: key-to-do-everything' \
Security protection
To prevent unallowed access to your store via REST API, you must specify a security X-Auth-Token key as an HTTP header in all your requests. The value for this parameter is set in the admin area preferences, Settings > API. REST API does not require users to be logged into the admin interface. A request will not be run if the key is not set up or empty.
What data can I pull?
Please refer to the API Reference for complete information about available endpoints, operations, and data types.
Actual API Reference for your particular store you can find by opening the URL YOUR-XCART-DOMAIN/api.