About Personalization Platform Services
- 4 minutes to read
The Personalization Platform provides several web services that expose REST API. In this article we will give you some guidelines on how to work with them.
Services
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.
- Asset Generator API creates Die-cut-templates and their 3D-mockups.
- Design Atoms API is 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.
- Storefront API - Products provides operations you need to make the integration using PIM products.
See more details in the What are Personalization Platform services article.
API Gateway
All these services are connected through an API Gateway. You can access it at:
https://api.customerscanvashub.com/
Important
If your Customer's Canvas tenant is hosted at the EU environment, you should use https://api.eu.customerscanvashub.com
Here, you will find a Swagger UI interface that allows you to play around with the API without writing any code.
Authorization
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 Bearer prefix:
Authorization: Bearer <token>
Tip
You may also use ExternalApp ClientId/ClientSecret in Swagger UI (Authorize button) and tools like Postman to automatically receive a proper token.
URLs
The API URL structure is always the same:
https://api.customerscanvashub.com/api/{short-service-name}/{version}/{endpoint}
The service that returns Swagger specs (as OpenAPI v3) has a similar structure:
https://api.customerscanvashub.com/openapi3/{short-service-name}/{version}
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 |
| Asset Generator | asset-generator | Info URL | Swagger specs |
| Design Atoms API | atoms | Info URL | Swagger specs |
| Storefront API | storefront | Info URL | Swagger specs |
| Storefront Products API | storefront-products | Info URL | Swagger specs |
API clients
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 C# API Client for more details on how to get started.
Generate it from an OpenAPI document
As you have already noticed, you can get a Swagger spec for each service and create an API client yourself. You may use your favorite tools - NSWag, Open API Generator, Jane, Swagger Editor/Codegen, and others. They allow you to generate an API client for the most popular platforms and languages - PHP, Python, JavaScript, Java, C#, and many more.
Warning
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.