The BackOffice backend provides several web services that expose REST API. In this article we will give you some guidelines on how to work with them.
At the moment, these are the following backend services:
- Asset Storage API - manages Customer's Canvas data, CRUD operations for the designs, fonts, images, etc.
- Asset Processor API - works with Customer's Canvas data when you need to process it, e.g. importing designs, getting previews, and similar operations.
- Design Atoms API - mostly needed when working with the design object model, e.g. when you create your own editor.
- Storefront API - provides all the operations you need to make the integration with an online store or e-commerce system.
See more details in the Back-End Architecture article.
All these services are connected through an API Gateway. You can access it at:
Here, you will find a Swagger UI interface that allows you to play around with the API without writing any code.
Backend services authorization is based on OAuth2 protocol. At the moment, it supports a client credentials flow. To sign in, you need to request a token from
https://customerscanvashub.com/connect/token by sending a Client ID and Client Secret, which you create in your Customer's Canvas account in Settings -> External Apps.
Once you receive an access token, you need to send it along with each request in the
Authorization header with the
Authorization: Bearer <token>
You may also use ExternalApp ClientId/ClientSecret in Swagger UI (Authorize button) and tools like Postman to automatically receive a proper token.
The API URL structure is always the same:
The service that returns Swagger specs (as OpenAPI v3) has a similar structure:
The table below puts it together. The info endpoint can be used as the simplest example of a working URL - feel free to copy it to Postman or another API testing tool and modify the address to the required endpoint.
|Service||Short name||Info endpoint||Swagger|
|Asset Storage||storage||Info URL||Swagger specs|
|Asset Processor||processor||Info URL||Swagger specs|
|Design Atoms API||atoms||Info URL||Swagger specs|
|Storefront API||storefront||Info URL||Swagger specs|
Although you may use the HTTP client to send HTTP requests to the API endpoints directly, it is not the most efficient way to work with API. Constructing JSON payloads before each call is error-prone and hardcoding endpoint URLs is no fun. It's as different as using a dynamically typed vs statically typed language!
You have the following options:
Use official API clients
So far we provide two API client types:
- .NET API client (both .NET Core and .NET Framework)
- TypeScript API client for Angular
You can install them from Nuget/npm. You will get all necessary data models implemented as native classes and also special HTTP client wrapper classes for making API calls.
See the Using API in a C# application for more details on how to get started.
Generate it from an OpenAPI document
Unfortunately, most of the tools don't support 100% of the OpenAPI v3 specification. They may fail to generate the correct code for certain endpoints. In this case, you may need to change the auto-generated code manually.
If the tools don't support the OpenAPI v3 specification but can work with OpenAPI v2, feel free to contact us. We can provide you with the v2 specs if it is more convenient for you.
Write a wrapper yourself
You don't have to learn the code generation tools and use the Swagger files at all. For example, if there are no tools for your platform, or if you just need to use a couple endpoints and you consider creating a separate library is excessive. In this case, just write mappers to transform your data structures into JSON payloads and a wrapper for the HTTP client manually.
Now you have an idea of how to work with the backend services. Let's take a look at the Design Editor APIs more closely.