Introducing our new Postman workspace.
Commerce Layer is built for developers. Every day, we work hard to ensure that developers building with Commerce Layer have a better developer experience than they had yesterday, making their work more efficient. In addition to our existing train of developer tools, we have revamped our existing Postman collection, and we’re happy to announce our new Postman page. With this update, you can fork our collections, watch for changes, get notified when something changes, and test our APIs with Postman efficiently. Most developers already know what Postman is. But if you don’t yet: Postman is an API developer tool with quite some useful features used by millions of developers to build and test APIs. In this article, we will explore the new workspace and show you how to get started with it.
Getting started
Our new public workspace is searchable and accessible through the Postman Public API Network. In the workspace, you will find our collection named Commerce Layer API (2022-06-30) with a dynamic ISO date suffix that changes whenever a new release is pushed. This collection includes List, Create, Retrieve, Update, and Delete API documentation and request sandbox for all the resources supported by our API.
In the following steps, we’ll show you how to get started with using our Postman collection.
1. Visit the Postman page and select the “Commerce Layer API” collection.
2. Click on the “Fork” icon to fork the collection into your personal Postman account.
3. Enter a name for your fork, select a workspace to fork into (this can be your personal or team workspace), and ensure to check the “Watch original collection” box. This will enable you to receive notifications in Postman when there are changes to the original collection.
After clicking the “Fork Collection” button, the fork process will begin and you can view the fork in your workspace.
Make API requests
All requests to Commerce Layer API must be authenticated with an OAuth2 bearer token. To get an access token, you need to execute an authorization flow using a valid application type as the client. Each application type has its usage, authentication flow, and permissions. There are three application types: sales channel, integration, and webapp. Each of these applications can be authenticated with different authorization grant flows using the available authorization grant types as described in the table below:
- The client credentials grant type gives you a "guest" access token to both sales channel and integration applications.
- The password grant type gives you an access token to sales channel applications in exchange for customer credentials.
- The authorization code grant type is used by backend applications to exchange an authorization code for an access token.
- The refresh token grant type is used by clients to exchange a refresh token for an expired access token.
Each access token generated based on the application types gets a specific set of permissions. For example, sales channel applications can read resource lists only for SKUs, SKU options, prices, promotions, and bundles. Anything outside this will require another application type. You can read the documentation to learn more about the available roles and permissions or for further information on authentication with Commerce Layer APIs. We also have a JavaScript authentication library you can easily use to generate any type of access token.
To make it easier to make requests across all the resources with the same credentials, you can create an Environment to use across the forked collection following the steps below.
1. Click on the “Environments” tab and click on “Create Environment” at the top left corner of the page.
2. Fill out the form and add a subdomain and access_token variable with your Commerce Layer organization slug and access token.
3. Click on the “💾 Save” icon to save the environment variables you have created.
4. You can also edit the name of the Environment by highlighting the existing “New Environment” name just above the form. You will see an edit icon you can click on to enter a new name.
If everything is added correctly, you can head back to the collection, select the environment and begin making use of the collection. For example, I just used the SKU resources to List all SKUs, and all I had to do was hit the “Send” button.
Pull changes
Just like GitHub, with Postman, you can send pull requests with new changes, merge pull requests, and pull changes from the source collection. When you receive a notification that we have released a new version of our collection, you can follow the steps below to pull in the changes.
- Click on the collection you forked.
- You will find a button with three dots somewhere after the share button. Click on that and select “Pull changes” from the dropdown list (PS: this option will only be clickable when there are changes to pull.
- You can also select “View Changelog” to see what has changed.
- Explore the new changes if you want and click the “Pull changes” button.
- After some time, the changes would be pulled in!
Conclusion
Our Postman collection is a great way for you to explore Commerce Layer as a new user and see what the data from our API resources look like. As an existing developer, you can also use the collection to test certain resources and validate the expected data/headers before making the actual request in your application using our JavaScript SDK, for example.
If you’re a visual person, you can watch the short video below that summarises all the steps we discussed earlier.