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.

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

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

20. sysco.no
Comparison I
• http://www.slideshare.net/SmartBear_Software/api-strat-
2014metadataformatsshort

21. sysco.no
Comparison II
• http://forums.raml.org/t/how-is-this-different-from-swagger/24/8

22. sysco.no
Comparison III
• http://www.mikestowe.com/blog/2014/07/raml-vs-swagger-vs-api-
blueprint.php

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

26. sysco.no
A Norwegian Sample

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

35. sysco.no
REST Binding

36. sysco.no
REST Binding

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

39. sysco.no
Sample JSON Reference

40. sysco.no
Sample XML 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»

47. sysco.no
Java EE/RAML Sample

48. sysco.no
Java EE/RAML Sample

49. sysco.no
Java EE/RAML Sample

50. sysco.no
Q & A

51. sysco.no
Enjoy the AMIS conference!
SYSCO 2016