Introduction to REST API Architecture and JSON Format

REST Service in Sterling Order Manager System Mohamed Jawahar Hussain Senior Staff Software Engineer IBM Software Lab, IBM India Pvt. Ltd. Jitendra Buge Senior Staff Software Engineer IBM Software Lab, IBM India Pvt. Ltd.

Introduction to REST API REST stands for Representational State Transfer. REST is web standards based architecture and uses HTTP Protocol for data communication. It revolves around resource where every component is a resource and a resource is accessed by a common interface using HTTP standard methods. REST was first introduced by Roy Fielding in 2000. In REST architecture, a REST Server simply provides access to resources and REST client accesses and presents the resources.

Introduction to REST API Here each resource is identified by URIs/ global IDs. REST uses various representations to represent a resource like text, JSON and XML. Now a days JSON is the most popular format being used in web services. A web service is a collection of open protocols and standards used for exchanging data between applications or systems. Web services based on REST Architecture are known as RESTful web services. These web services use HTTP methods to implement the concept of REST architecture. A RESTful web service usually defines a URI, Uniform Resource Identifier a service, provides resource representation such as JSON and set of HTTP Methods.

Introduction to REST API Following well known HTTP methods are commonly used in REST based architecture. GET - Provides a read only access to a resource. PUT - Used to create a new resource. DELETE - Used to remove a resource. POST - Used to update a existing resource or create a new resource. OPTIONS - Used to get the supported operations on a resource.

Introduction to JSON format JSON: JavaScript Object Notation. JSON is a syntax for storing and exchanging data. JSON is text, written with JavaScript object notation. When exchanging data between a browser and a server, the data can only be text. JSON is text, and we can convert any JavaScript object into JSON, and send JSON to the server.

Introduction to JSON format JSON syntax is derived from JavaScript object notation syntax: Data is in name/value pairs Data is separated by commas Curly braces hold objects, Square brackets hold arrays Sample XML and the equivalent JSON format: <PersonDetails> <Person> <Name> Jawahar </Name> <Location> Bangalore </Location> </Person> </PersonDetails> { "PersonDetails": { "Person": { "Name": " Jawahar ", "Contact": " 9880040372 " } } }

Rest API in IBM Sterling OMS XML API (XAPI) capabilities are now accessible through a simple REST API layer. Now customization developers can create, read, update, and delete resources by using HTTP calls that are compliant with REST standards. Benefits: Supports JSON and XML input and output Easier to work with existing data store abstractions in Dojo Reduces reliance on custom HTTP client code REST API features are enabled with standard installs and updates as of version 9.4. To configure the REST servlet, edit the xapirest.properties file. For detailed REST API reference documentation, view the Javadoc files in the <install>/xapidocs/restdoc directory.

Rest API in IBM Sterling OMS Calling List APIs Access List APIs with GET HTTP requests. List APIs return a list of records that match the criteria that is specified in the request parameters. 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. Request format Format to call List APIs: http://host:port/contextRoot/restapi/Name?parameters The following example shows a REST call to getOrganizationList: GET http://host:port/contextRoot/restapi/organization?IsNode=Y&OrganizationName=~like~DEMO

Rest API in IBM Sterling OMS Calling Create APIs Access Create APIs with POST HTTP requests. Create APIs insert new resource entries into the database. REST Create requests use the following types of APIs depending on the Name of the resource that is specified: manageName (with Operation=Create) manageNameHierarchy (with Operation=Create) createName createNameHierarchy For example, Create requests for orders use createOrder, and Create requests for organizations use manageOrganizationHierarchy. To see the complete list of resources and APIs, view the REST Javadoc files.

Rest API in IBM Sterling OMS Calling Create APIs Format to call Create APIs: http://host:port/contextRoot/restapi/Name The following example shows a Create request for an order: POST http://host:port/contextRoot/restapi/order You can use the "manage" APIs to update a resource if it exists or create the resource if it does not exist in a single Create-Or-Modify request. To Create-Or-Modify through REST, submit a PATCH to the Name of the resource collection and pass a document that describes the resource in the request body. PATCH http://host:port/contextRoot/restapi/Name

Rest API in IBM Sterling OMS Calling Detail APIs Use the following HTTP request format to call Detail APIs: GET http://host:port/contextRoot/restapi/Name/id The following example shows a Detail API call for an order with OrderKey = 12345: GET http://host:port/contextRoot/restapi/order/12345 The following example shows a Detail API call that uses the detail resource with parameters: GET http://host:port/contextRoot/restapi/order/detail?EnterpriseKey=DEFAULT &OrderNo=Y1234&DocumentType=0003

Rest API in IBM Sterling OMS Calling Modify APIs Use the following HTTP request format to call Modify APIs: PATCH http://host:port/contextRoot/restapi/Name/id The following example shows a request to modify an order with an OrderKey equal to 12345: PATCH http://host:port/contextRoot/restapi/order/12345 You can make Modify calls with PUT if you set servlet.put.enabled to true in the xapirest.properties file.

Rest API in IBM Sterling OMS Calling Delete APIs REST Delete requests use the following APIs depending on the Name of the resource that is specified. Use the following HTTP request format to call Delete APIs: DELETE http://host:port/contextRoot/Name/id The following example shows a request to delete an order with OrderKey equal to 12345: DELETE http://host:port/contextRoot/restapi/order/12345

Rest API in IBM Sterling OMS Properties to be set in customer_overrides.properties. xapirest.yif.apifactory.protocol=LOCAL xapirest.servlet.authstyle=OPEN xapirest.servlet.userid=admin xapirest.servlet.put.enabled=true xapirest.servlet.realm=prompt xapirest.yif.httpapi.userid=admin xapirest.yif.httpapi.password=password

Invoking Service through REST in IBM Sterling OMS URL to call REST API for service would be: http://localhost:8084/smcfs/restapi/executeFlow/TestService Input to service will be encapsulated with the service name. For example: Input data for getOrderdetails such as <Order EnterpriseCode="DEFAULT" OrderNo="Y100002801"/> Will be represented as <TestService> <Order EnterpriseCode="DEFAULT" OrderNo="Y100002801"/> </TestService>

Invoking Service through REST in IBM Sterling OMS For invoking a service, we would need to have a XSL translator to parse the input to an appropriate input to the API call.

Invoking Service through REST in IBM Sterling OMS For invoking a service, we would need to have a XSL translator to parse the input to an appropriate input to the API call.

THANK YOU

Disclaimer The information contained in this presentation is provided for informational purposes only. While efforts were made to verify the completeness and accuracy of the information contained in this presentation, it is provided As Is , without warranty of any kind, express or implied. In addition, this information is based on IBM s current product plans and strategy, which are subject to change by IBM without notice. IBM shall not be responsible for any damages arising out of the use of, or otherwise related to, this presentation or any other documentation. Nothing contained in this presentation is intended to, or shall have the effect of: Creating any warranty or representation from IBM (or its affiliates or its or their supplies and/or licensors); or Altering the terms and conditions of the applicable license agreement governing the use of IBM software.