Get started with the TypeScript SDK
Learn how to set up and use the TypeScript SDK.
This step-by-step guide leads you through setting up and making API calls using the TypeScript SDK.
Objectives of the get started guide
By the end of this guide you will have:
A Project with a configured API Client.
The following (or later) must be installed before the TypeScript SDK can be used:
- Node v12.22.7
- npm v6 OR yarn v1.22.17
Example code in this getting started guide uses placeholders that should be replaced with the following values:
|project_key||your API Client|
|client_id||your API Client|
|secret||your API Client|
|scope||your API Client|
Install the TypeScript SDK
Use the following commands to install SDK components from npm or Yarn.
|Machine Learning API|
|Audit Log API|
The SDK Client and the HTTP API must be installed. The Import API, Machine Learning API, and Audit Log API are only needed for more specific use cases.
Create a ClientBuilder file
Create a new file called
BuildClient.ts and insert the following code.
This code creates a Client that is used to make API calls.
Using this example code configures
httpMiddlewareOptions to handle auth and HTTP requests respectively. You can configure and use other middleware based on your requirements and add them to
ctpClient with method chaining:
Create the Client
Create a new file and include the following code:
apiRoot can now be used to build requests to the Composable Commerce API.
This code includes
getProject() as an example. If you run this code, the Project is returned.
How to structure your API call
Add an endpoint
An endpoint should be added to
apiRoot. The following targets the Shopping List endpoint:
If your IDE supports auto-complete, the full list of endpoints can be viewed.
If no endpoint is specified, the Project is referenced.
Query a specific entity using withID() or withKey()
To query a specific entity (such as an individual Shopping List), include its
Add the method
After selecting the endpoint, select a method to use.
get() is used to query entities.
post() is used to create and update entities.
.delete() is used to delete entities.
Adding parameters and payloads
Parameters for querying entities can be included within
get(). Parameters and payloads for updating and creating entities should be included within
When getting the Shopping List endpoint, optional parameters can be included to modify what Shopping Lists are returned:
When posting to the Shopping List endpoint, a
body payload must be included. This payload (ShoppingListDraft) creates a new Shopping List:
When posting to a specific Shopping List, a
body payload must be included. This payload (
ShoppingListUpdate) updates the specified Shopping List:
.execute() .then() .catch()
.execute() sends the API request.
.then() adds functionality that should follow the API request. In the following example code,
then() is used to output the response to the console.
.catch() should be included for assisting with debugging and error handling.
Using the TypeScript SDK in the browser
The TypeScript SDK can also be used in a web browser.
Create an HTML file and insert the following code:
When loaded in your web browser this page displays a button that, when clicked, returns your Project information.
getProjectDetails() function is similar to code examples within this get started guide. Consult the previous code examples to add further functionality to the HTML document.
Try our example code
Continue learning about the TypeScript SDK by checking our SDK code examples. You will find example code for creating, querying, and updating Customers and Products.