Custom endpoints

You can use provided HCL Commerce REST API to create your own custom API endpoint, such as to retrieve data for use with custom applications or for sending to other HCL or third-party services.

Creating a custom endpoint

When you are creating a custom endpoint, your endpoint can be a wrapper around existing HCL Commerce Storefront (Transaction server) REST API. Your custom endpoint can also be custom code that you want to use with your HCL Commerce store or environment.

Any custom API and endpoints that you create for your store must be created and packaged within a development environment that is based on HCL Commerce Developer for use within the Customization server. Within the development environment, a new custom-endpoints archive is included as a package within the commerceue-ear project. You can use this package to create your resource API. A sample resource that you can use as a reference is included within this package. This sample resource is an example of a custom endpoint that integrates with HCL Commerce REST API.

When you are creating your own custom endpoint, you need to include your custom code with the custom-endpoints/src/main/java/com/ibm/commerce/custom/rest directory of commerceue-ear project. This project includes a CustomApplication class for binding resources to the custom endpoints application.

To view this binding process, un-comment the SampleResource class for the CustomApplication class and review the code processing within debug mode. The SampleResource class includes a sample API integration with the HCL Commerce Storefront REST API.

Authentication

Any custom endpoints that you create are unprotected by default. If you are writing your API to query or access Storefront REST API, which has more privileges for accessing data and services, ensure that you include the required authentication. Any API that uses a custom endpoint must be authenticated before the API can access any default Storefront REST API. Authentication for Storefront REST API uses tokens, which are specific to HCL Commerce for authentication and are called "WC tokens".

The WC tokens that you must use to authenticate your custom endpoints are the same as what a shopper uses for login in to your HCL Commerce store. WC tokens are generated for authenticating shoppers for a HCL Commerce store whenever a shopper logs into the store. The login identity API is called to authenticate the shopper and generates the required tokens. For more information, see the Authentication and Session Management REST API.

To obtain your own WC tokens, such as for testing a custom endpoint, call the login identity API. The tokens are included within the response for the login identity request. Include your WC tokens as HTTP request headers for your Storefront REST API requests.

To learn more about how to authenticate your custom endpoints, review the sample resource for custom endpoints that is included within HCL Commerce Developer. Use the sample resource as a model for authenticating your custom endpoints.

This sample resource shows how to authenticate a custom endpoint with a WC tokens to get shopper data and how to authenticate a request for more privileged data, such as data that is not about the shopper that is issuing the request. The authentication to obtain more privileged data uses additional authentication provided by HCL Commerce. This additional authentication uses a JSON Web Token (JWT) that is generated by HCL Commerce to authenticate requests. Use this sample resource to help you learn how to structure and use your own custom endpoints to authenticate with both WC tokens and JWT for obtaining data other than the shopper's data.

Sample custom endpoint

A sample custom endpoint resource is provided with three example APIs that call two Storefront REST APIs and one external, third-party API. These example API also show the different options for authenticating a custom endpoint.

To try the sample resource custom endpoint in your programming environment, open the /custom-endpoints/src/main/java/com/ibm/commerce/custom/rest/CustomApplication.java class for editing. Un-comment the line where the SampleResource class is added to the custom application. Save and restart your commerceue application.

s.add(SampleResource.class);

When you call the sample custom endpoint API, the WC tokens are validated. If the validation is successful (service response is 200 OK), the processing of the request continues. You can use this sample as a model for writing your own custom endpoints.

The sample resource includes requests to the following REST APIs:

Get all stores.
The resource calls this API to query the Transaction server to obtain a list of all stores.
```
curl -X GET \
 https://{domain}:{port}/rest/custom/sample/store-list-with-jwt \
 -H 'Content-Type: application/json' \
 -H 'WCToken: {WCToken}' \
 -H 'WCTrustedToken: {WCTrustedToken}'
```
This API request first authenticates the user with WC tokens. If successful, a JWT is generated for the shopper's request and signed for use in authenticating the API request for obtaining the store data. The JWT authentication is required because the store data is privileged data that a shopper cannot obtain with WC token authentication.
Get the shopper's user account data:
```
curl -X GET \
 https://{domain}:{port}/rest/custom/sample/person-with-wctokens \
 -H 'Content-Type: application/json' \
 -H 'WCToken: {WCToken}' \
 -H 'WCTrustedToken: {WCTrustedToken}'
```
The resource calls this API to query Storefront REST API to retrieve data about the user that is calling the API. The response includes the contextual data for the user that is issuing the REST API call.
This API request uses the WC tokens for authentication because the request is scoped to the shopper's data.
The sample resource also includes an example of a custom endpoints API that wraps an external, third party REST API. This resource queries a REST API that is hosted on IBM Cloud Functions to get the message 'Hello World'.
```
curl -X GET \
 https://{domain}:{port}/rest/custom/sample/call-cloud-function \
 -H 'Content-Type: application/json' \
 -H 'WCToken: {WCToken}' \
 -H 'WCTrustedToken: {WCTrustedToken}'
```
This API request uses the WC tokens for authentication.