Using IBM Integration Bus to support the API economy Presented at IBM InterConnect 2016 conference

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

2. 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.

3. 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

4. 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

5. 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

6. 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

7. 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

8. 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

9. 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

10. 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

11. REST APIs – Swagger Editor
11

12. 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

13. REST APIs – new project wizard
13

14. 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

15. REST APIs – REST API Description view
15

16. 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

17. 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

18. REST APIs – accessing parameter information
• E.g. accessing REST parameters from a graphical mapping node
18

19. 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

20. 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

21. 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

22. 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

23. REST APIs – web user interface
23

24. 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

25. 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

26. 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

27. 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

28. REST APIs – Swagger UI
28

29. 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

30. 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

31. 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

32. 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

33. Push REST API from IIB Toolkit
33

34. APIm – API definition from IIB
34

35. Creating a ‘plan’ in APIm
35

36. Creating a ‘plan’ in APIm
36

37. Publishing an API plan
37

38. 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

39. 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.

40. 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.

41. 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.