Adding assets via the Chec API

5 min read
by Jaeriah Tay
August 5, 2020

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.

Commerce.js Demo store thumbnail

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

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!

You might also like