Exposing REST Services in Sterling OMS

Introduction:

Prior to IBM Sterling OMS v9.4, it was only possible to expose APIs/Services as SOAP web service. REST API features are enabled now with standard installs and updates of IBM Sterling OMS v9.4 onwards.

XML API (XAPI) capabilities are now accessible through a simple REST API layer. Developers can create, read, update, and delete resources by using HTTP calls that are compliant with REST standards.

Both SOAP and REST have their own Pros and Cons. But here we will just focus on basics of enabling REST services with examples.

Benefits:

• Supports both JSON and XML input and output

• Easier to work with existing data store abstractions in Dojo

• Reduces reliance on custom HTTP client code

Sterling side configuration:

• To configure the REST servlet, you need to edit the properties in <sterling_install>/properties/xapirest.properties file.

• For that, It is recommended to use the <sterling_install>/properties/customer_overrides.properties file to override properties. Refer the below table for Property details. Here, I have explained about 'servlet.authstyle' property with two values for simplification as these values are good to start with. For other values and it's implementation you need to read IBM documentation in detail.

• Prefix the property name with ‘xapirest’ to override the property. Eg- To override ‘servlet.authstyle’ property, mention it like ‘xapirest.servlet.authstyle’ in customer_overrides.properties file.

  

• After changing the customer_overrides.properties,

• run setupfiles command from <sterling_install>/bin folder
• run buildear command from <sterling_install>/bin folder
• you can pass -Dnowebservice=true during buildear (unlike SOAP web service where you must pass -Dnowebservice=false)
• deploy the new .ear file to your Application Server

• Default behavior is a LOCAL API call (yif.apifactory.protocol=LOCAL) . This may be set to HTTP or HTTPS along with other properties instead if you want to support calls over HTTP/HTTPS. Refer yifclient.properties and xapirest.properties for full documentation.

• For detailed REST API reference documentation, view the Javadoc files in the <sterling_install>/xapidocs/restdoc directory.

Accessing the REST Servlet:

The REST servlet is deployed to handle resources under the URL - https://host:port/contextRoot/restapi/

You can access List, Detail, Create, Modify, and Delete APIs through the REST layer with GET, POST, PATCH, and DELETE HTTP requests.

Specifying HTTP Headers:

Certain requests require setting HTTP headers. Some important one’s are below.

Invoking REST services:

By default Sterling exposes all the Synchronous Services as Restful Web Services. You can use any tool like - SoapUI or Postman to invoke REST services.

• Calling any API/Service with POST HTTP requests

I would suggest to go with this methodology for Production environments for calling any type of API/Service.

Calling APIs - To call any API with its full input, send a POST HTTP request to /invoke/apiName

Ex - http://localhost:8085/smcfs/restapi/invoke/getOrderList

Calling Services - You can also call any custom service with a POST to /executeFlow/serviceName. I have created a custom api named 'TestService', which internally calls getOrderDetails API for testing purpose.

Ex- http://localhost:8085/smcfs/restapi/executeFlow/TestService

• Calling List and Details APIs with GET HTTP requests

REST List requests use getNameList APIs, where Name is the type of resource that you specify in the request. To see the complete list of resources and APIs, view the REST Javadoc files.

Use the following HTTP request format to call List APIs:

GET https://host:port/contextRoot/restapi/Name?parameters

Ex - To make a REST call to getOrganizationList :

http://localhost:8085/smcfs/restapi/organization?OrganizationCode=DEFAULT

• Calling Modify APIs with PATCH HTTP requests

Access Modify APIs with PATCH HTTP requests. Modify APIs update the information of existing resources.

• Calling Delete APIs with DELETE HTTP requests

Access Delete APIs with DELETE HTTP requests.

Errors and status codes:

These are the normal HTTP status code categories.

• 1xx - Informational

• 2xx - Success

• 3xx - Redirection

• 4xx - Client Error

• 5xx - Server Error

If you think this is useful and want me to create more articles like this, then Please use comment box to give your valuable feedback and suggestions.