Adding assets via the Chec API
A well-designed API is flexible, approachable, and clear to understand.
At Chec/Commerce.js, we pride ourselves on the cleanliness of our API, how easy it is to integrate, and the variety of ways it can be used. With our API, we’re giving commerce developers the control and freedom to customize unique purchasing experiences on any medium.
As developers, there are many situations where we would rather make requests directly against the API, instead of using a dashboard user interface.
One example of this is uploading multiple assets and associating them to your products. Chec has a secure and comprehensive API to support uploading of assets with your flavor of server-side code such as Python, Perl, or good old fashioned cURL.
What are assets?
Files that exist alongside your data such as images and other various file formats are considered assets.
Below is an abbreviated data structure of a product with multiple assets within the assets array. Note that if a product image is added via the Chec dashboard, it will be posted to the product.media
endpoint as the feature image.
[
{
"id": "prod_RyWOwmQmmwnEa2",
"permalink": "lip-fantastic",
"name": "Lip Fantastic",
"description": "<p>A limited -edition, nourishing lip gel to top off your look and feel fantastic.</p>",
"price": {
"raw": 24,
"formatted": "24.00",
"formatted_with_symbol": "$24.00",
"formatted_with_code": "24.00 USD"
},
"quantity": 10,
"assets": [
{
"id": "ast_ZRjywM24Jo7Y8G",
"url": "https://cdn.chec.io/merchants/17851/assets/F1t7AVOogO3VZoxE|lippyf-3.jpg",
"data": {
"ext": "jpg",
"name": "lippyf-3.jpg",
"size": 1424347
},
},
{
"id": "ast_N7GKwbnbMw3EX4",
"url": "https://cdn.chec.io/merchants/17851/assets/wXlES92euFxsMFkY|roller-2.jpg",
"data": {
"ext": "jpg",
"name": "lippyf-2.jpg",
"size": 1443804
},
},
]
},
]
Required permissions
Creating new assets via the API requires authenticated access. In order to upload assets, you’ll need to use your secret key to make a POST request to the v1/assets
endpoint.
Now let’s walk through a simple guide to see this in practice!
Prerequisites
- A Chec account to obtain your secret key (Chec dashboard > Settings > Developer)
- A terminal
What we want to achieve
- Create new assets
- Associate uploaded assets to products
The Chec API supports uploading assets in various file formats. See a full list of accepted file formats here.
Lets get started!
1. Provide your image source
Either a base 64 encoded contents
argument or a url
argument with a remote URL needs to be included with the asset’s file content when making your request. We will be using cURL to make our calls so providing an image url would more practical in this case.
First upload some assets to a public image hosting platform. One that I usually use is imgbb. Make sure the links are publicly accessible.
2. Use the assets endpoint to create new assets
Using cURL request at this endpoint POST v1/assets
, you will need at minimum the below parameters:filename
(required): The asset filename.url
(optional): A remote asset URL. Required if contents
is not provided.contents
(optional): Base 64 encoded file contents. Required if url
is not provided.
Open up your terminal and type in the following code with the appropriate values.
curl -X POST
"https://api.chec.io/v1/assets"
-H "X-Authorization: {your_secret_key}"
-H "Content-Type: application/json"
-d '{"filename":"your-file-name.jpg", "url":"https:imgbb.com/your-file-name.jpg"}'
Let’s walk through each line of the request above. First we are using cURL to make a POST request to the https://api.chec.io/v1/assets
API endpoint. In the request headers, we need to include our secret key as the X-Authorization
header’s value and the default Content-Type
is application/json
. The data request body has to include the required parameters: your file name and URL of your file source.
Example of a successful response
{
"id": "ast_VNplJa1EaYwL60",
"url": "https://cdn.chec.io/merchant/123/assets/SH542KJlsd7h2Hdu-my-photo.jpg"
}
You can check to see a list of your uploaded assets by using a GET request.
curl -X GET
-G "https://api.chec.io/v1/assets"
-H "X-Authorization: {your_secret_key}"
To delete an asset you can simply include the asset ID at the same asset endpoint.
curl -X DELETE
-G "https://api.chec.io/v1/assets/ast_VNplJa1EaYwL60"
-H "X-Authorization: {your_secret_key}"
3. Associate your extra assets to each of your product
With your newly uploaded assets, you will now need to associate them to your products. Using the same cURL request format. Include the ID of the product that you want the assets to be added to, followed by the assets endpoint in the URL. In the data request body, the asset ID is the only parameter that is required. You can optionally specify a sort order number, which will sort the asset array being returned when requesting product data.
assets.*.id
(required): The asset ID to associate.assets.*.sort_order
(optional): Desired sort order for each asset.
Open up your terminal and type in the following code with the appropriate values.
curl -X POST
"https://api.chec.io/v1/products/prod_VNplJa1EaYwL60/assets"
-H "X-Authorization: {your_secret_key}"
-H "Content-Type: application/json"
-d '{"assets":[{"id":"ast_VNplJa1EaYwL60"}]}'
Example of a successful response
{
"success": true
}
4. List your products to check that assets are correctly associated with each product
curl -X GET
-G "https://api.chec.io/v1/products?limit=25"
-H "X-Authorization: {your_secret_key}"
Wow amazing! You’ve just interacted with the Chec API directly using cURL! With all your uploaded assets now added to your product data, you can now use the full payload of that object to build your beautiful application UI.
Requests made using cURL or any server-side code can work for write access to any resource endpoints that are not supported in the Chec Dashboard, for instance adding SKUs to your products.
We’re continuing to extend the dashboard UI to cater to these types of actions. Until then, you’ll just have to be a command line hero, making all your requests right in the terminal! For many of you that should come easily!
Resources and Community
Check out our documentation and community articles.
Join our community on Slack to connect with eCommerce developers from around the world. Share your projects with us, ask questions, or just hang out!