API access for Containers deployment

IBM® Sterling Intelligent Promising API documentation is available in an another container which can be deployed by IBM Sterling Intelligent Promising Operator. You can also deploy API documentation container externally that is without using the Operator.

Access API documentation

The following table lists the URLs to access API documentation for all the services.

Important: When you are using these URLs, replace <base_URL> with your domain address.

Service	URL
Inventory	<base_URL>/api-docs/inventory.html
Promising	<base_URL>/api-docs/promising.html
Configuration	<base_URL>/api-docs/configuration.html
Catalog	<base_URL>/api-docs/catalog.html
Carrier	<base_URL>/api-docs/carrier.html
Rules	<base_URL>/api-docs/rules.html

Deploy API documentation by using IBM Sterling Intelligent Promising Operator

To deploy API documentation by using the Operator, add apiDocsService to the SIPEnvironment spec. If apiDocsService is not defined in the SIPEnvironment, then the API documentation container is not deployed. For more information, see apiDocsService parameter.

Deploy API documentation deployment without IBM Sterling Intelligent Promising Operator

To deploy API docs externally that is without the IBM Sterling Intelligent Promising operator, use a docker container or Kubernetes. The URL to externally access API docs is <base_URL>/api-docs, where <base_URL> is http://localhost:<host_port>/. Use the following command to create a docker container of API documentation. For the <image_name>, see Registry image names for IBM Sterling Intelligent Promising Standard package.

docker run -p <host_port>:8080 --name <container_name> <your registry>/<image_name>

Authenticate APIs

You can authenticate APIs by using the JSON Web Token in an API call.

Generating JSON Web Tokens

JWT can be generated in the following two ways:

JWT generated from Order Management System Software (OMS)
Order Management System Software generates JWT after the JWT-related configuration is enabled. To get the token from OMS,
- Call login rest API in OMS by using loginid/password and fetch the user token from the API output
- Call /jwt?_loginid=<loginid>&_token=<user token fetched in previous step> rest endpoint in OMS to get the JWT
JWT generated from external system
You can setup your external system to generate the JWT that can be used to make API calls on IBM Sterling Intelligent Promising. Ensure to configure the public key in IBM Sterling Intelligent Promising JWT gateway verifier as explained in Creating a JWT issuer secret by using a public key.

The JSON Web Token needs to be passed as a bearer token in the request header for the API calls.

JWT payload

The following snippet is an example of a payload for JWTs. iss and exp are mandatory fields in the payload.

{
 “iss”: “oms”,
 “aud”: “sip”,
 “exp”: 1688772650,
 “nbf”: 1567771750,
 “sub”: “user”,
 “userID”: “user”,
}

Role based access for accessing APIs

To achieve optimal security and operational efficiency, Sterling Intelligent Promising Containers offer the following roles for accessing APIs.

Role	Description	API endpoints
BUSINESS	Users subscribed to the BUSINESS role run various business operation use cases. Subscribers to this role have access to all APIs with endpoints such as /inventory, /configuration, /catalog, and more.	https://<sip-domain>/inventory/* https://<sip-domain>/promising/* https://<sip-domain>/configuration/* https://<sip-domain>/catalog/* https://<sip-domain>/cas/* https://<sip-domain>/optimizer/*
OPERATIONS	Users subscribed to the OPERATIONS role manage deployments and set rules for tenants. Subscribers to this role have access to APIs with /operations endpoint.	https://<sip-domain>/inventory/operations/*
ADMINISTRATION	Users subscribed to the ADMINISTRATION role manage governance, user access, and other administrative tasks. Subscribers to this role have access to APIs for both business and operations roles, and also administrative APIs.	https://<sip-domain>/private/* Includes BUSINESS and OPERATIONS roles endpoints

To configure a service role in the JWT configuration secret, see Creating a JWT issuer secret by using a public key.

Invoke APIs

While invoking APIs, ensure to pass tenantId as default.

For example, https://<sip-domain>/inventory/<tenantid>/v2/availability/node.

Header

"Content-Type" : "application/json"
"Authorization" : "Bearer [JWT_token]"

Body

{
  "demandType": "OPEN_ORDER",
  "lines": [
    {
      "deliveryMethod": "SHP",
      "itemId": "sample0123",
      "lineId": "line_sample01234",
      "productClass": "NEW",
      "shipNodes": "["eastnode01"]",
      "unitOfMeasure": "EACH"
    }
  ],
  "segment": "ONLINE",
  "segmentType": "Channel"
}