Using IBM Integration Bus to support the API Economy Andrew Coleman Architect, IBM Integration Bus on Cloud Chair, W3C XML Query Working Group

Please Note:

2

•  IBM’s statements regarding its plans, directions, and intent are subject to change or withdrawal without notice at IBM’s sole discretion.

•  Information regarding potential future products is intended to outline our general product

direction and it should not be relied on in making a purchasing decision. •  The information mentioned regarding potential future products is not a commitment,

promise, or legal obligation to deliver any material, code or functionality. Information about potential future products may not be incorporated into any contract.

•  The development, release, and timing of any future features or functionality described for our

products remains at our sole discretion. •  Performance is based on measurements and projections using standard IBM benchmarks in a

controlled environment. The actual throughput or performance that any user will experience will vary depending upon many factors, including considerations such as the amount of multiprogramming in the user’s job stream, the I/O configuration, the storage configuration, and the workload processed. Therefore, no assurance can be given that an individual user will achieve results similar to those stated here.

Agenda

•  REST APIs overview •  How to implement a REST API in Integration Bus •  Protecting your backend systems with a workload management policy •  Pushing REST APIs from Integration Bus into APIm •  Using APIm to control the workload sent to Integration Bus

3

REST APIs

•  A REST API is a lightweight web service API based on HTTP – Much simpler alternative to SOAP based web services.

•  A REST API describes a set of resources, and a set of operations that can be called on those resources.

• Operations can be called from any HTTP client – Clients available for most programming languages – Callable from JavaScript code running in a web browser – Or application code running on a mobile device.

4

REST API

Mobile apps

Cloud apps

Web pages

Why build REST APIs in Integration Bus?

•  Integration Bus for universal connectivity – expose systems of record as REST APIs for easy consumption by web or cloud based clients: – MQ, CICS, TCP/IP, files, …

•  Ease of development – build an entire REST API around a database using the graphical mapper - without needing to write a line of code: – Alternatively, use your IIB language of choice (ESQL, Java, or .NET)!

•  Security – built in support for HTTPS (including client authentication) and basic authentication (LDAP servers).

• Monitoring – message flow and resource stats show how a REST API is performing; flow events provide auditing and business monitoring.

•  Scalable – deploy your REST API with multiple instances, or across multiple integration nodes and servers – Workload management policies to restrict or alert when traffic exceeds limits.

5

REST APIs - resources

•  A REST API has a base path – the root from which all of the resources and operations are available. E.g.: – http://mycompany.com:7843/customerdb/v1

•  Each resource in a REST API has a path, relative to the base path, which identifies that resource. Example resources might be: –  /customers - all of the customers in the database –  /customers/12345 - customer #12345 –  /customers/12345/orders - all orders for customer #12345 –  /customers/12345/orders/67890 - order #67890 for customer #12345

6

REST APIs - operations

•  Each resource in a REST API has a set of operations. – An operation in a REST API has a name, and an HTTP method, such as

GET, POST, PUT, or DELETE.

•  The combination of the path of the HTTP request and the HTTP method identifies which resource and operation is being called.

•  Example operations on the resource /customers/12345 might be: – GET getCustomer - retrieve the customer details from the database. – PUT updateCustomer - update the customer details in the database. – DELETE deleteCustomer - delete the customer from the database.

•  In order to call the updateCustomer operation, the HTTP client must make a HTTP PUT request to: – http://mycompany.com:7843/customerdb/v1/customers/12345

7

REST APIs - parameters

•  Each operation defined in a REST API can also specify a set of parameters. – Parameters can be used to pass information in to the operation.

•  Parameters are in addition to the body passed in the HTTP request. •  Integration Bus supports three different types of parameters:

– Path parameters – parts of the path can be defined as a variable. E.g. •  /customers/{customerId}/orders/{orderId} •  /customers/12345/orders/56789

– Query parameters – can be specified in the URL following the path: •  /customers?maxResults=5&name=2

– Header parameters – can be specified in the headers of the HTTP request: •  Api-Client-Id: ff6e2c5d-42d5-4026-8f7f-d1e56da7f777

8

REST APIs – Open API Initiative (f.k.a Swagger)

•  Swagger is an open standard for defining a REST API: – https://openapis.org

•  Also a set of open source tooling to interact with Swagger documents and the REST APIs that they describe.

•  Swagger document includes definitions of the resources, operations, and parameters in a REST API. – Can also include JSON Schema that describes the structure of the request

and response bodies to an operation. •  Analogous to a WSDL document for a SOAP web service. •  Integration Bus supports Swagger 2.0:

– https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md

9

REST APIs – developing a Swagger document

•  Sample Swagger document shipped with IIB v10: – <install root>/server/sample/restapis/swagger.json

•  Swagger Editor is an open source tool for authoring a Swagger document – can be downloaded and run locally, or is also hosted on the web – http://editor.swagger.io

• Once the Swagger document has been built in Swagger Editor, simply click on File, Download JSON. – JSON file can then be used with Integration Bus.

10

REST APIs – Swagger Editor

11

REST APIs – REST APIs in Integration Bus

•  IIB v10 introduces new REST API container. – Expose a set of integrations as a RESTful web service.

• Operations defined in the REST API are implemented as subflows. – Simply wire the flow between the Input and Output nodes.

•  Container routes inbound HTTP requests to the correct subflow. •  REST APIs support all of the Integration Bus features that you can use

with applications – E.g. shared libraries, monitoring, activity log. – All message flow nodes can be used within a REST API.

•  A REST API in Integration Bus requires a Swagger document. – Can be imported using the new ‘Create a REST API’ wizard. – Can also be built from scratch using the IIB REST API Editor

12

V10

REST APIs – new project wizard

13

REST APIs – REST API Description view

•  The REST API Description view is the starting point for a REST API. – View the list of the resources and operations defined in the REST API. – View any parameters that are defined for those operations.

•  Use the REST API Description view to implement an operation. – Click on an unimplemented operation to generate a subflow for that operation – Unimplemented operations will return HTTP 501 (Not Implemented) status

code to invoking client –  Implement error handling for a REST API.

•  Invoked if and exception is not handled by the subflow for an operation.

– Can also enable HTTPS from the REST API Description view.

14

REST APIs – REST API Description view

15

REST APIs – implementing an operation

• Once the ‘Implement the operation’ link is selected, an empty subflow is generated.

• When the operation is called by an HTTP client, a message will be passed to the Input node for the corresponding subflow.

•  The message contains – JSON request body, if a body has been provided in the request. – Parameters (path/query/header) in the LocalEnvironment tree.

• When the subflow completes and passes a message to the Output node, the response is passed back to the HTTP client.

16

REST APIs – mapping JSON request bodies

•  IIB v10 enhanced the graphical mapper with support for JSON.

•  JSON Schema information in the Swagger document defines the source and target trees within the graphical mapper.

17

V10

REST APIs – accessing parameter information

•  E.g. accessing REST parameters from a graphical mapping node

18

REST APIs – accessing parameter information

19

DECLARE max INTEGER -1;

IF FIELDTYPE(InputLocalEnvironment.REST.Input.Parameters.max) IS NOT NULL THEN

SET max = InputLocalEnvironment.REST.Input.Parameters.max;

END IF;

•  E.g. accessing REST parameters from a compute node (ESQL)

•  Equivalent logic can be coded in Java and .NET compute nodes

REST APIs – packaging and deployment

•  REST APIs are packaged into a BAR file – Similar to Applications & Integration Services

•  Deployed to an integration server using the standard mechanisms –  Integration Toolkit, command line, or Integration Java API.

•  REST API appears in the Integration Toolkit and web administration interface under a REST APIs category.

20

REST APIs – packaging and deployment

•  REST APIs cannot currently (as of V10 FP1) be used with the HTTP listener for the integration node, which is the default HTTP listener when a default queue manager is specified on the integration node. If you have a default queue manager, then you must explicitly enable the HTTP listener for the integration server. If you do not, then you will not be able to deploy the REST API.

•  The base path of the REST API can be used to isolate a REST API from other REST APIs, in a similar way to a context root for a J2EE application. The base path can also be used to isolate multiple versions of the same REST API on a single integration server – for example, you could have /customerdb/v1 and /customerdb/v2.

•  You cannot deploy a REST API that would clash with URLs being handled by other REST APIs deployed to an integration server, or HTTPInput nodes deployed outside of REST APIs.

21

REST APIs - administration

•  All administrative and operational controls that are available for applications in Integration Bus are also available for REST APIs.

•  The command line programs that work with applications will also work with REST APIs.

•  There is support in the Integration Java and administrative REST API for programmatically interacting with deployed REST APIs.

•  The web user interface shows the resources, operations, and parameters that are available in a deployed REST API.

22

REST APIs – web user interface

23

REST APIs – deployed Swagger

• When a REST API is deployed, its Swagger document is available for download. E.g. – http://localhost:7080/customerdb/v1/swagger.json

•  The deployed Swagger document is automatically updated to reflect the server, port, and HTTP/HTTPS details for the deployed REST API. – No need to update it with the correct details before deployment.

•  Use the deployed Swagger document in combination with open source Swagger tooling, to explore and invoke a deployed REST API.

24

REST APIs – Swagger UI

•  You can pass the URL of the deployed Swagger document to Swagger UI, which allows you to explore and test a deployed REST API. Swagger UI is available from: – http://petstore.swagger.io/ (live demo, but can also be used) – https://github.com/swagger-api/swagger-ui (source for download)

•  In order for Swagger UI to work, you must enable Cross-Origin Resource Sharing (CORS, see notes). – mqsichangeproperties IB10NODE -e default -o HTTPConnector -n

corsEnabled -v true

25

REST APIs – Cross-Origin Resource Sharing

•  A web page has an origin. The origin of a web page is the scheme, host, and port of the web server that is hosting the web page. For example, the origin of https://localhost:8080/test/index.html is https://localhost:8080.

•  When a web page makes a request for another web page or resource on the same origin, a same-origin request is made.

•  However, when a web page makes a request for another web page or resource on a different origin, a cross-origin request is made. This requires special support from the HTTP server that the cross-origin request is being made to. Without this support, the request is rejected by the web browser.

26

http://www.ibm.com /index.html /client.js /ui.css

https://iib-inst1.company.com /api/customers /api/customers/5 /api/customers/5/orders

Cross-origin request

REST APIs – Cross-Origin Resource Sharing

•  If you are making an HTTP request from a web page to a REST API or other HTTP service deployed to Integration Bus, it is likely that a cross-origin request will need to be made.

•  Integration Bus V10 now includes built in support for CORS. At V10 GA, this support was limited to the HTTP listener for the integration server, but as of V10 FP1 is available for the HTTP listener for the integration node as well.

•  The support is disabled by default, but can be easily enabled with a single command: •  mqsichangeproperties IB10NODE -e default -o HTTPConnector -n

corsEnabled -v true

•  The default settings for CORS should be sufficient for most needs, but additional configuration options are available for fine level control. When CORS settings are modified, the changes are effective immediately – there is no need to restart the integration server or node.

27

REST APIs – Swagger UI

28

REST APIs – Swagger Codegen

•  Swagger Codegen can be used to generate an SDK (software development kit) for a deployed REST API in a variety of languages – Java, C#, Objective-C, PHP, Python, Ruby – the list goes on!

•  Swagger Codegen is available from: – https://github.com/swagger-api/swagger-codegen

•  Invoke the generated SDK from your applications – No need to mess with low level HTTP transport.

•  A JavaScript client is also available – https://github.com/swagger-api/swagger-js

29

REST APIs – Swagger JavaScript client

•  Swagger Codegen does not support generating a static JavaScript client.

•  The Swagger team have provided a JavaScript client that can configure itself on the fly from a Swagger document. – This JavaScript client can be used in web pages and also in Node.js.

•  The JavaScript client is available from: – https://github.com/swagger-api/swagger-js

30

REST APIs – Workload Management

•  Apply rate limiting policies to APIs – (and all other IIB Integration types)

•  Reduces back-end server load

•  Administrator sets rate thresholds and actions – Notification: alert published when threshold exceeded – Delay: processing delay introduced to maintain rate

within threshold

•  Imposed on the flow – not on individual connected clients – API management required for finer grained control

31

0

20

40

60

80

100

120

140

160

180

200

0

20

40

60

80

100

120

140

160

180

200

Push to API Management (API Connect)

•  IIB supports pushing REST APIs into IBM API Management •  Enables centralized management of APIs exposed by IIB integrations

– Alongside other APIs available to the enterprise •  Supports versioning of APIs •  Create ‘plans’ to manage:

– Grouping of resources – Different access rights to parts of an API – Rate limits

•  Authentication – User: Basic Auth, etc – Application: Secret key

• Monitor usage and performance •  Developer portal enables discovery, testing & registration of apps

32

10.0.0.2

Push REST API from IIB Toolkit

33

APIm – API definition from IIB

34

Creating a ‘plan’ in APIm

35

Creating a ‘plan’ in APIm

36

Publishing an API plan

37

Summary

•  IIB now delivers first class support for REST APIs

•  New IIB container type (v10)

•  Supports OpenAPI Initiative (Swagger 2.0)

• Graphical mapper enhancements to support JSON transformation

•  New ‘Push to API Management’ support

38

Notices and Disclaimers

39

Copyright © 2016 by International Business Machines Corporation (IBM). No part of this document may be reproduced or transmitted in any form without written permission from IBM.

U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM.

Information in these presentations (including information relating to products that have not yet been announced by IBM) has been reviewed for accuracy as of the date of initial publication and could include unintentional technical or typographical errors. IBM shall have no responsibility to update this information. THIS DOCUMENT IS DISTRIBUTED "AS IS" WITHOUT ANY WARRANTY, EITHER EXPRESS OR IMPLIED. IN NO EVENT SHALL IBM BE LIABLE FOR ANY DAMAGE ARISING FROM THE USE OF THIS INFORMATION, INCLUDING BUT NOT LIMITED TO, LOSS OF DATA, BUSINESS INTERRUPTION, LOSS OF PROFIT OR LOSS OF OPPORTUNITY. IBM products and services are warranted according to the terms and conditions of the agreements under which they are provided.

Any statements regarding IBM's future direction, intent or product plans are subject to change or withdrawal without notice.

Performance data contained herein was generally obtained in a controlled, isolated environments. Customer examples are presented as illustrations of how those customers have used IBM products and the results they may have achieved. Actual performance, cost, savings or other results in other operating environments may vary.

References in this document to IBM products, programs, or services does not imply that IBM intends to make such products, programs or services available in all countries in which IBM operates or does business.

Workshops, sessions and associated materials may have been prepared by independent session speakers, and do not necessarily reflect the views of IBM. All materials and discussions are provided for informational purposes only, and are neither intended to, nor shall constitute legal or other guidance or advice to any individual participant or their specific situation.

Notices and Disclaimers Con’t.

40

It is the customer’s responsibility to insure its own compliance with legal requirements and to obtain advice of competent legal counsel as to the identification and interpretation of any relevant laws and regulatory requirements that may affect the customer’s business and any actions the customer may need to take to comply with such laws. IBM does not provide legal advice or represent or warrant that its services or products will ensure that the customer is in compliance with any law

Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products in connection with this publication and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. IBM does not warrant the quality of any third-party products, or the ability of any such third-party products to interoperate with IBM’s products. IBM EXPRESSLY DISCLAIMS ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

The provision of the information contained h erein is not intended to, and does not, grant any right or license under any IBM patents, copyrights, trademarks or other intellectual property right.

IBM, the IBM logo, ibm.com, Aspera®, Bluemix, Blueworks Live, CICS, Clearcase, Cognos®, DOORS®, Emptoris®, Enterprise Document Management System™, FASP®, FileNet®, Global Business Services ®, Global Technology Services ®, IBM ExperienceOne™, IBM SmartCloud®, IBM Social Business®, Information on Demand, ILOG, Maximo®, MQIntegrator®, MQSeries®, Netcool®, OMEGAMON, OpenPower, PureAnalytics™, PureApplication®, pureCluster™, PureCoverage®, PureData®, PureExperience®, PureFlex®, pureQuery®, pureScale®, PureSystems®, QRadar®, Rational®, Rhapsody®, Smarter Commerce®, SoDA, SPSS, Sterling Commerce®, StoredIQ, Tealeaf®, Tivoli®, Trusteer®, Unica®, urban{code}®, Watson, WebSphere®, Worklight®, X-Force® and System z® Z/OS, are trademarks of International Business Machines Corporation, registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at "Copyright and trademark information" at: www.ibm.com/legal/copytrade.shtml.

Thank You Your Feedback is

Important!

Access the InterConnect 2016 Conference Attendee Portal to complete

your session surveys from your smartphone,

laptop or conference kiosk.