Statistics notes ,it includes mean to index numbers
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
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
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
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
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
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
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