IBM WebSphere DataPower XC10

IBM WebSphere DataPower XC10 REST Gateway 2011 IBM Corporation This presentation will discuss the REST gateway provided with the IBM WebSphere DataPower XC10 Appliance. XC10_RESTAPIs.ppt Page 1 of 22

Agenda IBM WebSphere DataPower XC10 REST gateway Examples Enterprise integration example Summary 2 DataPower XC10 REST Gateway 2011 IBM Corporation This presentation will begin with a general discussion of the WebSphere DataPower XC10 REST gateway, followed by some examples of how to use the REST interface. XC10_RESTAPIs.ppt Page 2 of 22

Section IBM WebSphere DataPower XC10 REST gateway 3 DataPower XC10 REST Gateway 2011 IBM Corporation This section will describe the IBM WebSphere DataPower XC10 REST gateway. XC10_RESTAPIs.ppt Page 3 of 22

What is REST? REpresentational State Transfer REST APIs are implemented as HTTP patterns REST requests have patterns /resources/datacaches/<cachename>/<mapname>/<key> Example: http://myxc10.ibm.com/resources/datacaches/mycache/mycache/mykeystring 4 DataPower XC10 REST Gateway 2011 IBM Corporation REST is an acronym for representational state transfer. It is typically implemented as a servlet that responds to HTTP requests. The REST service accepts HTTP requests and parses them to determine what action to perform. The data that is sent to and returned from the servlet hosting the REST service depends on the type of request sent. REST requests have URIs with specific patterns. For example: /resources/datacaches/<cachename>/<mapname>/<key> XC10_RESTAPIs.ppt Page 4 of 22

WebSphere DataPower XC10 REST gateway Enables non-java clients to access simple data grids Supported on WebSphere DataPower XC10 firmware v1.0.0.4 or later Allows integration with IBM WebSphere DataPower XI50 Appliances Microsoft.NET applications Clients that cannot host the IBM Object Request Broker (ORB) 5 DataPower XC10 REST Gateway 2011 IBM Corporation The WebSphere DataPower XC10 REST gateway is intended to simplify integration of enterprise applications and software products with the WebSphere DataPower XC10 appliance. For example, a WebSphere DataPower XI50 Appliance can use the DataPower XC10 as a side-cache to minimize redundant requests to back-end systems and significantly improve response time. The REST gateway also provides integration with clients that cannot host the IBM ORB. The REST gateway is available on firmware version 1.0.0.4 or later. XC10_RESTAPIs.ppt Page 5 of 22

WebSphere DataPower XC10 REST API Basic data access and update Enabled by default Supported over the HTTP protocol on port 80 Supported over the HTTPS protocol on port 443 6 DataPower XC10 REST Gateway 2011 IBM Corporation The IBM WebSphere DataPower XC10 ObjectGrid programming API provides a full set of simple data grid data manipulation functionality. The features that you can call on the IBM WebSphere DataPower XC10 appliance using the REST API are a subset of the features available through the ObjectGrid programming model. The REST gateway is enabled by default and no additional configuration is necessary. There is no way to disable the REST interface. The REST gateway is accessed over HTTP on port 80 or HTTPS on port 443. XC10_RESTAPIs.ppt Page 6 of 22

Transport security Appliance provides a self-signed certificate for SSL sessions Same certificate is used for administrative console and REST API HTTPS clients must accept the SSL certificate during the SSL handshake to access the REST gateway 7 DataPower XC10 REST Gateway 2011 IBM Corporation You can use a secure connection when accessing the REST gateway by sending your request to HTTPS port 443. The HTTP client that you use to access the WebSphere DataPower XC10 REST gateway must accept self-signed SSL certificates in order to access your secured simple data grid. This functionality is supported by most HTTPS capable clients. XC10_RESTAPIs.ppt Page 7 of 22

WebSphere DataPower XC10 REST operations Basic simple data grid actions Insert, update, retrieve, and delete HTTP operations are used to perform those action when calling the REST API HTTP methods: GET POST DELETE Refer to the information center for full API descriptions 8 DataPower XC10 REST Gateway 2011 IBM Corporation The IBM WebSphere DataPower XC10 REST API provides basic data access and manipulation operations. The REST API requires that different types of HTTP methods be used depending on what action you want to invoke. For example, to insert or update an object in the simple data grid cache, you use an HTTP POST method. To retrieve an object from the simple cache, you use an HTTP GET method. XC10_RESTAPIs.ppt Page 8 of 22

Request pattern REST APIs are implemented as HTTP patterns REST requests have patterns /resources/datacaches/<cachename>/<mapname>/<key> Example: http://myxc10.ibm.com/resources/datacaches/mycache/mycache/mykeystring Eviction strategy <mapname>.lut Last update time <mapname>.lat Last access time Optional Time to live expiration add /<key>?ttl=<seconds> 9 DataPower XC10 REST Gateway 2011 IBM Corporation REST requests have URIs with specific patterns. For example: /resources/datacaches/<cachename>/<mapname>/<key> The first part of the URI ( /resources/datacaches ) routes the request to the REST gateway on the DataPower XC10 appliance. The next part of the URI is the cache name. You must specify the name of a simple data grid that already exists on the appliance. The third piece of the URI is the map name within the cache. A simple data cache always contains an ObjectMap with the same name as the simple data cache. You can dynamically create additional ObjectMaps by providing a specially formatted map name. By adding specific strings to an ObjectMap name you can tell the appliance how it should remove, or evict, objects when space is needed for new objects. The eviction policy can be based on an objects last update time or last access time. Each map is a separate data container within the simple data cache. If you create a map for automatic eviction you can specify a time-to-live value, in seconds, as an additional parameter on the request. The last part of the URI is a key. The key is used to address the specific piece of data stored in the cache. If you do not specify a key on a data insert, the REST gateway will automatically generate one and include it in the body of the HTTP reply. XC10_RESTAPIs.ppt Page 9 of 22

Data format and headers for REST calls Keys must be strings Data type stored in cache specified in HTTP header Examples Content-type: application/json" "Content-type: application/pdf" "Content-type: text/plain" "Content-type: text/html" Content-type: image/gif REST API requires HTTP basic authentication Cookies returned to client after initial REST call zsessionid SimpleToken Cookies should be included with subsequent HTTP requests that are part of the same session 10 DataPower XC10 REST Gateway 2011 IBM Corporation The XC10 REST API uses the Content-type header in your HTTP requests to identify the data format of the data that is stored in the simple data grid. You can store data of multiple content types in the same simple data grid, although the data retrieved by an HTTP GET request will match the content-type specified when the data was stored. The appliance does not interpret or change the data. It is stored as a byte array along with the specified content type. As an example, you insert an object with a content type text/xml. When an application performs a GET operation for the same cache key, the response content-type is text/xml and the body is a copy of the XML text that was stored. The WebSphere DataPower XC10 REST API requires HTTP authentication. When your client authenticates with the WebSphere DataPower XC10 appliance, two cookies are provided with the response. These cookies, zsessionid and SimpleToken, should be included in subsequent HTTP requests to WebSphere DataPower XC10 in the same session. XC10_RESTAPIs.ppt Page 10 of 22

HTTP response status codes Success codes in the 200 range are returned on successful calls to the REST gateway Error codes in the 400 and 500 ranges are returned on unsuccessful calls to the REST gateway Example success codes: HTTP 201, 202, 203 code Example unsuccessful codes: HTTP 400, 403, 404 See Information Center for which exact codes are returned for each REST API call 11 DataPower XC10 REST Gateway 2011 IBM Corporation Since REST API calls to the IBM WebSphere DataPower XC10 appliance are HTTP requests, HTTP response status codes are returned with each REST API invocation. HTTP response status codes are classified by the number they start with. HTTP response status codes that are in the 100 range are informational codes. HTTP response status codes that are in the 200 range are success codes. Response status codes in the 300 range are redirection status codes. Codes in the 400 and 500 range are client error and server error codes. Depending on the call you make to the WebSphere DataPower XC10 REST gateway, different success codes and unsuccessful HTTP response codes apply. It is best to check the IBM WebSphere DataPower XC10 information center to see what response codes apply to each REST API call. XC10_RESTAPIs.ppt Page 11 of 22

Section REST gateway examples 12 DataPower XC10 REST Gateway 2011 IBM Corporation This section will show some examples of REST API calls to the IBM WebSphere DataPower XC10 Appliance. XC10_RESTAPIs.ppt Page 12 of 22

Example: add or update an object HTTP method: POST HTTP header Content-type: text/html Pattern: /resources/datacaches/<simple cache name>/<map name>/<key> POST data to pass to the WebSphere DataPower XC10 appliance <h2>sample</h2><p>a <b>formatted</b> string</p> Example using Linux utility curl curl u <user>:<passwd> -H Content-type: text/html X POST d <h2>sample</h2><p>an <b>formatted</b> string</p> http://myxc10.ibm.com/resources/datacaches/mycache/mycache/keystring Returns html: <html>200</html> 13 DataPower XC10 REST Gateway 2011 IBM Corporation This example shows how you can insert an object into a WebSphere DataPower XC10 simple cache using the REST interface. Use the HTTP POST method to insert an object, specifying a data type description in the content-type header field. Then create a URL including the simple data grid name and the key used to store the data, which is included in the POST data pattern. An HTTP response code 200 indicates the data was successfully inserted. The body of the request contains the data to be stored in the simple data grid. This data object must be serializable. Internally the appliance wraps the supplied content-type and request body in an object of type com.ibm.websphere.xsa.restvalue. A Java application using the ObjectMap API can use the RestValue class to insert or get data from a map. XC10_RESTAPIs.ppt Page 13 of 22

Example: get an object HTTP method: GET Pattern: /resources/datacaches/<simple cache name>/<map name>/<key> Can use a web browser Example: http://<user>:<passwd>@myxc10.ibm.com/resources/datacaches/mycache/mycache/keystring Returns html: <h2>sample</h2><p>a <b>formatted</b> string</p> Sample If key does not exist returns html: <html>404</html> A formatted string 14 DataPower XC10 REST Gateway 2011 IBM Corporation This example shows how to retrieve the object stored on the previous slide. You do not need to specify the data format since it is stored on the appliance with the data. An HTTP response code 200 indicates the data was retrieved successfully and the requested data is included in the response body. An HTTP response code 404 indicates the specified key was not found in the cache. The Content-type text/html is included in the response header. XC10_RESTAPIs.ppt Page 14 of 22

Example: delete an object HTTP method: DELETE Pattern: /resources/datacaches/<simple cache name>/<map name>/<key> Example using Linux utility curl curl u <user>:<password> X DELETE http://myxc10.ibm.com/resources/datacaches/mycache/mycache/keystring Returns html: <html>200</html> 15 DataPower XC10 REST Gateway 2011 IBM Corporation This example shows how to delete the object stored on the previous slide. As with the GET, you do not need to specify the data format. An HTTP response code 200 indicates the data is no longer in the cache. If the requested key was not found in the cache the REST gateway will still return a 200 response code. If you omit the key string in the pattern the request will delete all data in the specified map. XC10_RESTAPIs.ppt Page 15 of 22

Section Enterprise integration example 16 DataPower XC10 REST Gateway 2011 IBM Corporation This section will show an examples of how you easily use the WebSphere DataPower XC10 as a side cache for other enterprise products by using the REST gateway. XC10_RESTAPIs.ppt Page 16 of 22

Integrating the XC10 with the XI50 Results side-cache for the IBM DataPower Integration Appliance XI50 Can significantly reduce load on back-end systems Eliminates redundant requests Improves response times Increases total system throughput 17 DataPower XC10 REST Gateway 2011 IBM Corporation The IBM DataPower XC10 appliance REST gateway allows the XC10 to be used as a Service Oriented Architecture (SOA) results side-cache for the WebSphere DataPower Integration Appliance XI50. Using the XC10 s simple data grid as a side-cache for an XI50 can significantly reduce the load on the back-end systems by eliminating redundant requests, improving the response time to clients and increasing total system throughput. XC10_RESTAPIs.ppt Page 17 of 22

High-level design: Using the XC10 as a side-cache for the XI50 Client Applications XML XML Proxy Existing Processing Flow REST Gateway Backend Systems Grid IBM DataPower XC10 Appliance 18 DataPower XC10 REST Gateway 2011 IBM Corporation This slide shows an overview of how you can use the XC10 as an SOA side cache for an XI50 appliance using the XC10 REST gateway. As client application requests are received, the XML Proxy inspects the URI, the XML body contents, or both, to determine if the request meets the criteria for being cached. This is based on the caching policy rules defined in the XI50. If the request is cacheable, the XML Proxy will perform a standard side-cache operation. Using the REST-based HTTP GET method, the XML Proxy will look to see if the request is cached on the XC10 appliance. If the HTTP GET returns an HTTP 404 NOT FOUND, meaning a cache miss, the XML Proxy will pass the request through to the existing processing flow on the application hosted in the back-end systems. The XML Proxy will then cache the response as it flows back through the XML Proxy to the client application. The XML Proxy will use the REST-based HTTP POST method to insert the response into the side-cache. If the incoming request was found in the cache, then the result is retrieved from the cache, bypassing the back-end systems, thus removing the latency introduced by the application and data layers. XC10_RESTAPIs.ppt Page 18 of 22

Section Summary 19 DataPower XC10 REST Gateway 2011 IBM Corporation This section will summarize the major features of the IBM WebSphere DataPower XC10 REST gateway. XC10_RESTAPIs.ppt Page 19 of 22

Summary The REST gateway enables non-java clients to access simple data grids on the WebSphere DataPower XC10 appliance REST APIs perform data operations on the DataPower XC10 appliance over HTTP The REST API supports a subset of the ObjectGrid API REST patterns are used to perform actions 20 DataPower XC10 REST Gateway 2011 IBM Corporation The IBM WebSphere DataPower XC10 REST gateway provides another communication option that allows non-java clients to access simple data grids on the appliance. The activities that can be performed with the REST API are a subset of the actions that are available using the ObjectGrid programming model. Depending on what actions you want to perform using the REST API, you will use different HTTP methods, such as POST, GET, and DELETE. The cache name and key values are specified in the HTTP request pattern, and data to be inserted into the cache is passed as POST data. Refer to the IBM WebSphere DataPower XC10 information center for full documentation regarding the REST APIs and the data necessary for each call. XC10_RESTAPIs.ppt Page 20 of 22

Feedback Your feedback is valuable You can help improve the quality of IBM Education Assistant content to better meet your needs by providing feedback. Did you find this module useful? Did it help you solve a problem or answer a question? Do you have suggestions for improvements? Click to send email feedback: mailto:iea@us.ibm.com?subject=feedback_about_xc10_restapis.ppt This module is also available in PDF format at:../xc10_restapis.pdf 21 DataPower XC10 REST Gateway 2011 IBM Corporation You can help improve the quality of IBM Education Assistant content by providing feedback. XC10_RESTAPIs.ppt Page 21 of 22

Trademarks, disclaimer, and copyright information IBM, the IBM logo, ibm.com, DataPower, and WebSphere are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of other IBM trademarks is available on the web at "Copyright and trademark information" at http://www.ibm.com/legal/copytrade.shtml Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both. Microsoft, and the Windows logo are registered trademarks of Microsoft Corporation in the United States, other countries, or both. Java, and all Java-based trademarks and logos are trademarks of Oracle and/or its affiliates. Other company, product, or service names may be trademarks or service marks of others. 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, NOR SHALL HAVE THE EFFECT OF, CREATING ANY WARRANTIES OR REPRESENTATIONS FROM IBM (OR ITS SUPPLIERS OR LICENSORS), OR ALTERING THE TERMS AND CONDITIONS OF ANY AGREEMENT OR LICENSE GOVERNING THE USE OF IBM PRODUCTS OR SOFTWARE. Copyright International Business Machines Corporation 2011. All rights reserved. 22 2011 IBM Corporation XC10_RESTAPIs.ppt Page 22 of 22