Create an Endpoint

You use endpoints to retrieve data by calling Buying and Billing APIs.

The Communications Open Storefront Framework provides a number of endpoints for calling the Buying and Billing APIs. See the Design Storefront and Self-Care Pages chapter in this guide for the complete list of endpoints and how they're mapped to the TMF APIs. You can also find the endpoints in the packages/core/plugins/common/endpoint/endpoints.js file and the Buying and Billing API URLs in the @oracle-dx4c-buying/common/endpoint/endpoint-urls/index.js file. You can use these default endpoints for calling the Buying and Billing APIs, or create an endpoint if you want to integrate a new API.

In the Plans widget example, the promotion offering or plan data is returned by the list-product-offerings endpoint, which maps to the /productCatalogManagement/v4/productOffering Buying API.

Here's the directory structure for the list-product-offerings endpoint:

/plugins
    /endpoints
        /product-offering                   
         index.js
         meta.js
         /list-product-offering
            index.js
            meta.js

You create the index.js and meta.js files for your endpoints in this directory. Here's the sample /plugins/endpoint/product-offering/list-product-offerings/index.js file:

/*
 ** Copyright (c) 2020 Oracle and/or its affiliates.
 */
 
import {getProductOfferingsUrl} from '@oracle-dx4c-buying/common/endpoint/endpoint-urls';
import {handleEndpointResponse, getBuyingEndpointRequest} from '@oracle-dx4c-buying/common/endpoint/endpoint-saga';
import {LIST_PRODUCT_OFFERINGS} from '@oracle-dx4c-buying/common/endpoint/endpoints';
 
/**
 * Return an object that implements the endpoint adapter interface.
 */
const listProductOfferings = {
  /** The id of the endpoint */
  endpointId: LIST_PRODUCT_OFFERINGS,
 
  /**
   * Return a Fetch API Request object to be used for invoking the endpoint.
   *
   * @param payload Optional payload to be included in the request
   * @param state The current application state
   * @return Request object for invoking the endpoint via Fetch API
   */
  async getRequest(payload, state) {
    const {categoryName, type, expand, limit, priceListName} = payload;
 
    const queryParams = {
      'category.name': categoryName,
      type,
      expand,
      limit,
      'productOfferingPrice.priceList.name': priceListName
    };
 
    return getBuyingEndpointRequest(state, LIST_PRODUCT_OFFERINGS, getProductOfferingsUrl(queryParams), payload);
  },
 
  /**
   * Return a Fetch API Response object containing data from the endpoint.
   *
   * @param response The Response object returned by the fetch call
   * @param state The current application state
   * @param payload Optional payload that was included in the request
   * @return Response object, augmented with an async getJson function to return
   * an object to be merged into the application state
   */
  getResponse(response, state, payload) {
    return handleEndpointResponse(response, state, payload);
  }
};
 
export default listProductOfferings;

The getRequest function in this file generates the request to call the GET method of the productOfferings Buying API. It adds the appropriate query parameters and passes the request onto the getBuyingEndpointRequest function. The getBuyingEndpointResponse function generates the appropriate authorization headers for the calling the Buying API.

async getRequest(payload, state) {
  const {categoryName, type, expand, limit, priceListName} = payload;
 
  const queryParams = {
    'category.name': categoryName,
    type,
    expand,
    limit,
    'productOfferingPrice.priceList.name': priceListName
  };
 
  return getBuyingEndpointRequest(state, LIST_PRODUCT_OFFERINGS, getProductOfferingsUrl(queryParams), payload);
},

The getRequest function passes the response of the endpoint into the handleEndpointResponse function. This function parses the raw response from the Buying API and converts it into the desired UI model. This function also throws an endpoint error if the response has any issues.

export function handleEndpointResponse(response, state, payload = {}) {
  let json;
  const {parser} = payload;
  response.getJson = async () => {
    if (json === undefined) {
      json = await getBodyAsJson(response);
      if (response.ok) {
        json.headers = response.headers;
 
        return parser ? parser(json, state) : json;
      }
      throw new EndpointError(response, payload);
    }
 
    return json;
  };
 
  return response;
}

When you create an endpoint, you must also create the appropriate meta.js file. Here's the sample /plugins/endpoint/product-offering/list-product-offerings/meta.js file. This file specifies the package ID of the endpoint. The package ID must be unique for each endpoint.

/**
 * Metadata for the _listProductOfferings endpoint.
 */
export default {
  packageId: '@oracle-dx4c-buying/endpoints'
}; 

To export the references to the list-product-offerings endpoint and any other product-offering related endpoints, add the following In the /plugins/endpoint/product-offering/index.js file:

export const _listProductOfferings = () => import('./list-product-offerings');

Create a parallel reference in the /plugins/endpoint/product-offering/meta.js to export the references to the list-product-offerings endpoint metadata:

export * from '@oracle-cx-commerce/endpoints/meta';
 
// Export references to product-offering endpoints.
export {default as _listProductOfferings} from './list-product-offerings/meta';

Now export the list-product-offerings endpoint so that your application can recognize the endpoint. The /plugins/endpoint/index.js file contains a set of functions with the names that correspond to the names of your application's endpoints. Edit the /plugins/endpoint/index.js file to include the new endpoint:

export * from './product-offering'; 

Also, edit the /plugins/endpoint/meta.js file to include the new endpoint:

export * from './product-offering/meta';