Documentation

SDK setup process

Learn how to configure your environment for the TypeScript and Java SDK.

  • After completing this module, you should be able to:

    • Describe the general process required to set up the TypeScript and Java SDKs.

    • For developing projects with Composable Commerce, you'll need an integrated development environment (IDE). This module provides you with the steps to set up an IDE in two common programming languages: TypeScript (a superset of JavaScript) and Java. Choose either TypeScript or Java for your setup, depending on your specific needs.

    Install the SDK

    Both the TypeScript and Java tutorials will first take you through the steps to install the SDK on your machine. This includes making sure you have the right applications, runtime environments, and configurations before you begin.

    You will then be guided through setting up a local repository for your Composable Commerce Project.

    Test the SDK setup

    The second half of each SDK tutorial will guide you through running a test to see if your SDK setup is functioning correctly. If you can correctly execute the test, then you should be well-placed to complete the hands-on exercises in the remaining Developer Essentials modules.

    Testing the setup of either SDK focuses on two main tasks:

    • Creating an API client.
    • Building an API request.

    Please read the following sections before continuing on with the setup tutorials on the next pages.

    Create an API Client in the Merchant Center

    We need to create a Composable Commerce API Client to get credentials that can be used to access the Composable Commerce API.

    In our exercises in this learning path, we are working with customer data. To enable this, we need the manage_customers and view_customer scopes. To understand scopes and API Clients further, please read the Authorization flows and API Clients module. As a rule of thumb for setting scopes, follow the principle of least needed access rights. In other words, don’t give away more permissions than necessary.

    Log into your Composable Commerce Project and navigate to Settings > Developer settings. From here you can create a new API Client.

    1. Select Create new API client.
    2. Add a Name. You could use something like Dev Essentials Learning Path for now.
    3. In the Manage select Customers. This scope also includes view permissions for Customers.
    4. Select Create API Client.

    Merchant Center new API client screen with manage customers scope selected.

    Next, your API credentials will be displayed. Select the Environmental Variables (.env) option from the dropdown menu. Make a copy of the credentials or download them using the download button. Store these credentials securely, as you will not be able to access them again from the Merchant Center for security reasons.

    Please note, these tutorials teach you the essential skills to make your first requests against the Composable Commerce APIs. In some code examples, we included API credentials, to keep the examples brief.

    For actual project development, it's crucial to securely manage your API credentials. Use property or environment files and ensure secure access to these values.

    Build an API request

    After we have set up the API Client, we will be ready to send an API request to check that everything is working correctly.

    We will do so in two steps:

    Step 1: Set up an HTTP API Client in your SDK

    The client handles the repetitive parts for making a basic HTTP request, such as doing the Authentication flow, HTTP middleware, handling the Composable Commerce credentials, and error logging.

    Our API Client implements the Client Credentials Flow (see our Authorization flows and API Clients module if you haven't covered this yet). It fetches a token from the authorization server and then uses this token in all subsequent requests to the Composable Commerce APIs.

    As you are writing your own code to practice, remember to replace the variables with the API Client that you created in the Merchant Center. Remember the fields? They were:

    • projectKey
    • clientId
    • clientSecret
    • scope
    • API URL
    • Auth URL

    Step 2: Write a request

    The second step in our test will be to send a request to read a Customer record. Some of these API actions could be similar to what an integration between a customer relationship management platform and Composable Commerce would handle.

    As we want to fetch a Customer’s data, we will need to first make sure that we have a Customer ready at hand. If you have created a Project with the sample data, you should have a Customer already in your Project. If not, you can create Customers in the Merchant Center.

    As we will later learn in the Manage resources with the SDK module, you can fetch a Customer by ID or key. To simplify things for our very first call, we will use the ID.

    In the Merchant Center, navigate to Customer list and select the Customer that you just created. Look for the ID in the URL. It appears between the /customers/ and /general sections of the path, for example:

    Customer detail page in Merchant Center with customer ID highlighted in a red box.

    You will then be able to use this ID in your request.

    Now that you have an idea of the whole process involved in setting up the SDK, select one of the SDKs to install on your machine: TypeScript or Java.