Using IBM WebSphere Liberty and Swagger to Make your Services Accessible
- 1. Using IBM WebSphere Liberty and Swagger to Make your Services Accessible Arthur De Magalhaes
- 2. Agenda • The API Economy • Defining API with Swagger • API Discovery with Liberty • Demonstration • Feedback 1
- 5. API Economy – Mobile App Assembly 4
- 6. API Economy – API Providers 5
- 7. Where does WAS fit in the API Economy? • WAS is a great place to provide services • Customers already have thousands of services deployed on WAS today - we can help to define and expose them • Make it easy to implement and expose new services • WAS is a great place to consume services • Make it easier to access services from within WAS, e.g. simple configuration, generating client code • Easily expose, test, document, and integrate services into applications running on WAS 6
- 8. Defining API via Swagger
- 9. What is Swagger? • Swagger is the industry-leading specification for defining REST APIs • API is defined via JSON or YAML files (a “Swagger doc”) • Swagger is: – API documentation (or at least the metadata for it) – The contract between producer and consumer – The metadata needed to generate client code, server stubs, tests, …. 8
- 10. What is Swagger? • Large open source community with various projects on GitHub: – Online editor and GUI to browse and test API – Client-side code generation (26 languages) – Server-side code generation (9 languages) – Lots of other utils available, e.g. generation to HTML or PDF documentation – Over 2,000 related open-source repositories, with 15,000 daily downloads • Base specification for Open API Initiative (https://openapis.org/), under the Linux foundation 9
- 11. Swagger Yaml Example 10 (example edited for clarity) paths: /pet: post: summary: Add a new pet to the store consumes: <mime type> produces: <mime type> parameters: - in: body name: body description: Pet object that needs to be added to the store required: true schema: $ref: '#/definitions/Pet' responses: '405': description: Invalid input security: - petstore_auth: - 'write:pets' - 'read:pets'
- 12. Swagger UI 11 paths: /pet: post: tags: - pet summary: Add a new pet to the store description: '' operationId: addPet consumes: - application/json - application/xml produces: - application/xml - application/json parameters: - in: body name: body description: Pet object that needs ... required: true schema: $ref: '#/definitions/Pet' responses: '405': description: Invalid input security: - petstore_auth: - 'write:pets' - 'read:pets'
- 13. Using Swagger with Java EE • RESTful API are usually implemented via JAX-RS – JAX-RS annotations already provide basic Swagger information (overlap with a Swagger doc) – Swagger annotations allow you to augment JAX-RS beans with the remaining information and generate Swagger doc – Can still use a separate Swagger doc instead, but harder to keep in sync • RESTful API can also be implemented via servlets – Need to use a separate Swagger doc 12
- 14. API Discovery with Liberty
- 15. API Economy with Liberty • What are the challenges when using Swagger with Java EE? – Merging Swagger from annotations and standalone docs – UI for rapid API development and unit testing – Exploring all available APIs – Generating code to call external services • Liberty can help with all of these things! 14
- 16. API Discovery • New apiDiscovery-1.0 feature makes API from all applications discoverable via a single RESTful endpoint: /ibm/api/docs • Query parameter allows filtering based on context root • Supports both JSON and YAML • Application participation can be configured in server.xml (Swagger location, on/off) 15 Applications Liberty REST Admin UI API Connect
- 17. API Discovery OSGi SPI • An SPI interface is available for Liberty extensions to contribute their APIs into the aggregated master Swagger document • This is the same mechanism that allows Liberty runtime bundles (batch, JMX connector, etc.) to contribute their RESTful endpoints Admin UI Applications Liberty REST APIProviders API Connect
- 18. API Discovery Scenarios • Liberty supports any path toward API discovery: Top-Down (Documentation before Code) – Embed an existing Swagger doc inside an application – Swagger can be created manually or through an editor (e.g. API Connect, or Swagger’s online editor) Bottom-Up (Code before Documentation) – Swagger doc is generated by the runtime based on annotations in the application (JAX-RS, Swagger, or both) Mixed – Existing Swagger doc merged with generated Swagger from annotations – E.g. Apps that have some JAX-RS and some non-JAX-RS services 17
- 19. API Discovery User Interface • Based on the Open Source Swagger UI • Available at /ibm/api/explorer 18
- 20. API Discovery Collective Support • Enabling apiDiscovery-1.0 on a collective member will expose its aggregated Swagger documentation through the controller. • Endpoints: – /ibm/api/collective/docs – /ibm/api/collective/explorer 19 Admin UI Repository membersREST controller API Connect
- 21. API Discovery Cloud Scenario • Push a Liberty package into Bluemix • cf push <yourappname> -p wlp/usr/servers/defaultServer • Creates an auto-discoverable container in the cloud. 20 Admin UI app app app WLP API Connect
- 22. API Discovery Subscription • POST ibm/api/docs/subscription • Request: { docType: string} • Returns: { feedURL : wss://ibm/api/docs/subscription/websocket/{id}, feedType: websocket } • The client opens WSS connection and receives updates in real-time • Equivalent collective support at /ibm/api/collective/docs/subscription • Works with either webSocket-1.0 or webSocket-1.1 21
- 23. Integration with API Connect 22 IHS DB A A WAS Liberty Auto scale with Collectives PUBLIC | DEDICATED | LOCAL API Connect Administrator product.json+ swagger.json product.json Continuous Integration product.json Source Repository Swagger processor API Connect CLI product.json+ swagger.json
- 24. WebSphere Developer Tools Support • Authoring Swagger document (main doc or stub) through templates and skeleton • Includes JSON and Swagger-based validation. • Auto-generate JAXRS 2.0 client from Swagger document or URL • Can point to a running Liberty instance or Collective Controller and generate a JAXRS client that can connect to any of the exposed services! 23
- 25. Demonstration
- 26. Demonstration • Walk through a sample JAX-RS + Servlet application within WDT • Demonstrate how Swagger JSON can be authored using the tools • Deploy the application onto Liberty and walk through the raw document and generated UI • Use the UI to test the application endpoints • If time permits: demonstrate auto-generation of JAX-RS 2.0 clients from the Swagger document • If time permits: demonstrate triggered push to API Connect 25
- 27. Notices and Disclaimers 26 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. 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
- 28. Notices and Disclaimers Con’t. 27 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.
- 29. 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.