Presentation from OUGN 2016 - Experiences With REST in SOA Suite/OSB - WADL and RAML, sample from Norwegian online service

1. sysco.no
Experiences with REST on OSB/SOA Suite
Jon Petter Hjulstad
OUGN 2016

2. sysco.no
Overview
• About Speaker / Sysco
• Why REST ?
• A Norwegian sample
• REST Support is in SOA Suite / OSB
• 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
• Member of OUGN Board
• Twitter: jphjulstad
• Blog: http://blog.sysco.no/
Info

4. sysco.no
Company Facts
• Established in 2004
• More than 100 employees
• 7 Office Locations
• Bergen, Haugesund, Lima, Oslo, Stavanger, Stord, Ølen
• 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

6. sysco.no
Why REST?

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’.
• 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
Overview of RESTful API Description Languages
• Web Services Description Language 2.0 (WSDL)
• Web Application Description Language (WADL)
• Open Data Protocol (OData)
• Swagger
• RESTful Service Description Language (RSDL)
• RESTful API Modeling Language (RAML)
• API Blueprint
• Apache Avro

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
WADL
• WADL (Web Application Definition Language)
• WADL for REST services can be compared to a WSDL for SOAP
service
• WADL is used in SOA Suite / OSB
• Would be good if all REST services have a definition, but this is not
allways the case

13. sysco.no
RESTful API Modeling Language (RAML)

14. sysco.no
RAML Technology Primer
• https://www.youtube.com/watch?v=tGcfv7HsAnE
• By Chris Muir – «I like RAML!!»

15. sysco.no
RAML
• RAML 1.0 is available
• Aimed at full lifecycle of API
• Focused on reuse
– Resource Types
– Traits
• Documentation
• Test data (mocking)
• Detailed Specification
• I think also RAML is my favorite

16. sysco.no
A Norwegian Sample

17. sysco.no
Norwegian datasets
• http://hotell.difi.no/
• Want to look at
municipalities
• http://hotell.difi.no/api/json/difi/geo/kommune

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

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

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

21. sysco.no
REST Support in SOA Suite / OSB

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

23. sysco.no
SOA Suite provides the following REST support
• Support in SOA composite applications:
– Enable REST support in new or existing services.
– Integrate with external REST APIs.
– Support for XML, JavaScript Object Notation (JSON) (with automatic translation to and from XML), URI sample, and
URL-encoded GET/POST data.
– Generation of sample URI for REST service operations.
– Support for WADL services. The WADL can be provided by a deployed Oracle SOA Suite or Oracle Service Bus
service or a non-Oracle SOA Suite or Oracle Service Bus service such as a Jersey REST service.
• Ease of development:
– Oracle JDeveloper wizard provides several options for modeling REST interfaces and WSDL operation bindings:
• Manually define resource paths and REST operations to generate an underlying WSDL that contains the
mapping from the REST definition to the WSDL.
• Select the WSDL of the service component or external reference from which to map WSDL operations to
resource paths and HTTP verbs.
• Select a WSDL from many sources (for example, the application server or SOA-MDS) from which to
automatically populate the REST adapter with operation mappings.
– Readable API that publishes each method used upon deployment.
– Ability to browse and consume Oracle REST endpoints (including Oracle Service Bus) from within Oracle JDeveloper.
• Oracle Web Service Manager (OWSM) policy support for REST security.
https://docs.oracle.com/cloud/latest/soacs_gs/SOASE/soa-rest-integration.htm

24. sysco.no
The 2 choices we have
1. Utilizing an existing WADL
2. Creating an WADL using the Wizard in Jdeveloper
In most cases we will have to create the WADL manually
This can be reused
Resource Paths
Operations
Parameters
Request / Response

25. sysco.no
REST Binding

26. sysco.no
REST Binding

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

28. sysco.no
Sample WADL for our JSON Reference

29. sysco.no
Sample JSON Reference

30. sysco.no
Sample XML Reference

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

32. 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
• Amis - Maarten
has a blog post

33. sysco.no
Q & A

34. sysco.no
Enjoy the cruise!
SYSCO 2016