REST - Why, When and How? at AMIS25
0 likes1,087 views
This document provides an overview of REST APIs and discusses why REST is commonly preferred over SOAP. It describes various REST API description languages (ADLs) like Swagger, RAML, and WADL and compares their support in Oracle products. It also provides examples of describing a sample Norwegian dataset API in RAML and implementing REST support in SOA Suite, including creating WADLs from other ADLs or using the REST adapter. The document concludes with discussing REST support in Java EE and Oracle PaaS products.
![sysco.no
REST - properties
• URI format -
[protocol]/[server]:[port]/[servicename]/[resource]/{resource id}
• Parmameters
– As part of URI
– As body
– As a query parameter
– As a request header
• Verbs
– GET, PUT, POST, DELETE, OPTIONS, HEAD](https://image.slidesharecdn.com/syscorestsupportjphjulstad-160606045255/85/REST-Why-When-and-How-at-AMIS25-29-320.jpg)
Ad
More Related Content
What's hot (20)
Viewers also liked (20)
Ad
Similar to REST - Why, When and How? at AMIS25 (20)
Ad
More from Jon Petter Hjulstad (11)
Recently uploaded (20)
REST - Why, When and How? at AMIS25
- 1. sysco.no REST – Why, When and How? Jon Petter Hjulstad + Arturo & Jorge AMIS 25 – Beyond the Horizon
- 2. sysco.no Overview • About Speaker / Sysco • Why REST ? • REST ADLs – who is the winner ? • A Norwegian sample • REST Support is in SOA Suite / OSB • REST Support in Oracle PaaS • Q&A
- 3. sysco.no Information about me • Jon Petter Hjulstad • Dept Manager for Middleware at Sysco • 20 years experience with Oracle Products • Focusing on WLS, SOA Suite, BPM Suite ++ • SOA Partner Community Award 2012 • WLS Partner Community Award 2015 • Oracle ACE Associate • Twitter: jphjulstad • Blog: http://blog.sysco.no/ • Sysco is now part of Red Expert Alliance Info
- 4. sysco.no Company Facts • Established in 2004 • More than 100 employees • 9 Office Locations • Bergen, Haugesund, Lima, Oslo, Stavanger, Stord, Ølen, Copenhagen, Stockholm • 162 mNOK revenue in 2015 • Industry focus on Utilities, experts on Oracle technology About SYSCO 2009-2014
- 5. sysco.no We deliver the Red-Stack - Engineered systems - Exadata, Exalogic, ODA, BDA, PCA - Business Intelligence - Analytics - Visualizer - Big data - Database - Oracle VM - Integration, SOA - Identity Management IDM - Cloud - Application Foundation - Application Builder - MCS - DBaaS - Licenses LMA - Customer Experience CX Oracle Center of Excellence
- 7. sysco.no Why REST? • Why would anyone choose SOAP (Simple Object Access Protocol) instead of REST ? • The general rule of thumb: ‘Unless you have a definitive reason to use SOAP use REST’. • REST-JSON vs REST-XML • JSON: Simple syntax, less “markup” • XML: More complex, mature, Schema, XSLT, Xquery, Namespaces etc.
- 8. sysco.no REST vs SOAP • Why REST? – REST uses standard HTTP – so it is much simpler – REST permits many different data formats - SOAP only permits XML – REST has better performance and scalability – Smaller messages – less overhead – Mobile developers know REST • Why SOAP? – Wider support for transaction support – Better support for transaction support/security - WS-Security, WS- AtomicTransaction, WS- ReliableMessaging – More robust error handling – Your developer tools may not support REST yet
- 9. sysco.no REST vs SOAP for Mobile Applications • A-Team has done a comparison – look at http://www.ateam- oracle.com/performance-study-rest-vs-soap-for-mobile-applications/ • REST-JSON is 9 to 30 times faster than SOAP in mobile applications
- 10. sysco.no REST APIs • Beginning – Lack of standards • Now - Broad set of standards • Would be good if all REST services have a definition, but this is not always the case – And there in not one de facto standard
- 11. sysco.no Goals of Metadata APIs • Common goal of current metadata formats for REST APIs is to specify (*): – Entry point(s) – Resource paths – Methods to access these resources (GET, POST, PUT, etc.…) – Parameters that need to be supplied with these methods (Query, Template, HTTP Header, etc.) – Formats of inbound / outbound messages/representations (JSON Schema, XML Schema, Relax NG, etc.) – Status codes and error/fault messages – Documentary information (descriptions, etc.) for all these – Example data *) http://apiux.com/2013/04/09/rest-metadata-formats/
- 12. sysco.no Overview of RESTful API Description Languages (ADL) • Web Services Description Language 2.0 (WSDL) • Web Application Description Language (WADL) • Open Data Protocol (OData) • Swagger – OpenAPI • RESTful Service Description Language (RSDL) • RESTful API Modeling Language (RAML) • API Blueprint • Apache Avro
- 13. sysco.no Oracle Product support for REST APIs From Luis Weir: http://www.soa4u.co.uk/2016/05/converting-adls-to-implement-end-to-end.html
- 14. sysco.no WADL • WADL (Web Application Definition Language) • WADL is used in SOA Suite / OSB and Process Cloud Service • XML Description • Submitted to WWC by Sun 2009 – but no plan to standardize • The older of the mentioned standards • Not much used
- 15. sysco.no Swagger • SmartBear supported • Broad adoption • Swagger improved in many ways on WADL • Great tooling • Limited support of JSON Schema, no support of XML schemas
- 16. sysco.no RESTful API Modeling Language (RAML)
- 17. sysco.no RAML Technology Primer • https://www.youtube.com/watch?v=tGcfv7HsAnE • By Chris Muir – «I like RAML!!»
- 18. sysco.no RAML • RAML 1.0 is available since may 16th, 2016 • 0.8 is the version you normally will see supported • Aimed at full lifecycle of API • Focused on reuse – Resource Types – Traits • Documentation • Test data (samples) • Detailed Specification • I think also RAML is my favorite
- 19. sysco.no RAML 1.0 • Data types: a unified, streamlined, and powerful way to model data wherever it appears in an API. – Uniformly covers bodies, URI parameters, headers, and query parameters and eliminates the need for a separate formParameters construct – Supports wrapping XML Schema and JSON Schema and even referring to sub-schemas, but in many cases just obviates the schemas – Simplifies coding, compared to the JSON Schema or XML Schema, by being YAML-based • Multiple Examples: expressible in YAML, and annotatable so that semantics can be injected • Annotations: a tried-and-tested, strongly-typed mechanism for extensibility • Libraries: improved modularity for broad reuse of API artifacts • Overlays and Extensions: increased extensibility through separated files • Improved Security Schemes: – Wider OAuth support – Support for pass-through (key-based) security schemes – Support for signatures From spec: https://github.com/raml-org/raml-spec/releases/tag/1.0
- 23. sysco.no API-Transformer • Transform API Descriptions from/to various formats - Developed by APIMATIC – Online tool
- 24. sysco.no API-Transformer • Is also an API
- 25. sysco.no Transformation • What will you loose going from one ADL to another ? • A detailed comparison would be useful • Normally would have to make one file «flatten» to be able to transform
- 27. sysco.no Norwegian datasets • http://hotell.difi.no/ • Want to look at municipalities • http://hotell.difi.no/api/json/difi/geo/kommune
- 28. sysco.no Norwegian datasets • http://hotell.difi.no/api/xml/difi/geo/kommune • Can use pagination: add ?page=2 to URL to see next page • Can search/filter: – /api/json/difi/geo/kommune?query=levanger – /api/json/difi/geo/kommune?fylke=05 • Can get metadata – /api/json/difi/geo/kommune/fields
- 29. sysco.no REST - properties • URI format - [protocol]/[server]:[port]/[servicename]/[resource]/{resource id} • Parmameters – As part of URI – As body – As a query parameter – As a request header • Verbs – GET, PUT, POST, DELETE, OPTIONS, HEAD
- 30. sysco.no REST - operations Verb Operations performed on server Impact GET Read a resource No impact (change) on resource PUT Insert a new resource or update if it already exists Idempotent POST Insert a new resource or update if it already exists Non idempotent DELETE Delete a resource Idempotent OPTIONS List the allowed operations on a resource No impact (change) on resource HEAD Return only response headers and no response body No impact (change) on resource Safe = no impact on the resource Idempotent = the same result, no matter how often you call it PUT: only creates a resource if you provide all the values including the ID (requires a complete URI) POST: create a new resource every time it is called, or update the resource if it already exists From: Lonneke Dikmans presentation at UKTech15
- 31. sysco.no REST Support in SOA Suite / OSB
- 32. sysco.no REST - support • Before 12.1.3 REST support had to be done by hand in OSB – Or in Spring Adapter or Socket Adapter (have seen blogs) • SOA Suite 12.1.3/12.2.1 supports WADL • SOA Suite 12.1.3 added REST adapter – inbound and outbound • SOA Suite 12.2.1 supports End-To-End JSON with JavaScript • Mobile Cloud Service (MCS) supports RAML – Use Node.js to implement • This presentation will show use of the REST adapter (reference)
- 33. sysco.no Outbound - The 3 choices we have 1. Utilizing an existing WADL 2. Creating a WADL from a different ADL description 3. Creating an WADL using the Wizard in Jdeveloper All services should be modeled in an ADL Resource Paths Operations Parameters Request / Response
- 34. sysco.no Inbound - The 2+1 choices we have 1. Utilizing an existing WADL 2. Creating an WADL using the Wizard in Jdeveloper Given that you have to make service description available as WADL 3. Make API available in different ADL by manually adding that – or make it part of pipeline
- 37. sysco.no WADL • The application element forms the root of a WADL description and contains the following (XML): – Zero or more doc elements – An optional grammars element – Zero or more resources elements – Zero or more of the following: • resource_type elements • method elements • representation elements • param elements https://en.wikipedia.org/wiki/Web_Application_Description_Language
- 38. sysco.no Sample WADL for our JSON Reference
- 41. sysco.no Use Cases • SOAP Service – Expose as REST – Common case for Mobile Apps • REST Service – Expose as SOAP – SOAP enabling for «old-school» • Technology Adapter – Expose as REST – Database Tables, Procedures – LDAP – Socket • Composite REST Service – Bottom-up designed service
- 42. sysco.no SOA Suite 12.2.1 end-to-end JSON • Performance • Reuse JavaScript Competence • Some things will be easier to implement • Can mix JSON / SOAP
- 43. sysco.no REST Support in Oracle PaaS
- 44. sysco.no Too many facets? • Mobile Cloud Service -> RAML • API Platform -> Swagger / Blueprint • SOA CS -> WADL It is good to have support for many standards but also some consistency is much needed when it comes to API / REST design
- 45. sysco.no REST Support in Java EE
- 46. sysco.no Java EE/RAML Integration • Bottom/Up approach – Turning your JAX-RS annotations into RAML specifications. – Reusing Swagger annotations to document REST services • Top/Down approach – Turning your RAML specifications into JAX-RS interfaces – «Contract-first»
- 50. sysco.no Q & A
- 51. sysco.no Enjoy the AMIS conference! SYSCO 2016