rest - why, when and how? at amis25

sysco.no

REST – Why, When and How? Jon Petter Hjulstad

+ Arturo & Jorge

AMIS 25 – Beyond the Horizon

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

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

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

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

sysco.no

Why REST?

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.

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 maynot support REST yet

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

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

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/

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

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

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

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

sysco.no

RESTful API Modeling Language (RAML)

sysco.no

RAML Technology Primer

• https://www.youtube.com/watch?v=tGcfv7HsAnE

• By Chris Muir – «I like RAML!!»

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

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

sysco.no

Comparison I

• http://www.slideshare.net/SmartBear_Software/api-strat-

2014metadataformatsshort

sysco.no

Comparison II

• http://forums.raml.org/t/how-is-this-different-from-swagger/24/8

sysco.no

Comparison III

• http://www.mikestowe.com/blog/2014/07/raml-vs-swagger-vs-api-

blueprint.php

sysco.no

API-Transformer

• Transform API Descriptions from/to various

formats - Developed by APIMATIC – Online tool

sysco.no

API-Transformer

• Is also an API

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

sysco.no

A Norwegian Sample

sysco.no

Norwegian datasets

• http://hotell.difi.no/

• Want to look at

municipalities

• http://hotell.difi.no/api/json/difi/geo/kommune

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

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

sysco.no

REST - operationsVerb 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 resourceIdempotent = the same result, no matter how often you call itPUT: 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

sysco.no

REST Support in SOA Suite / OSB

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)

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

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

sysco.no

REST Binding

sysco.no

REST Binding

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

sysco.no

Sample WADL for our JSON Reference

sysco.no

Sample JSON Reference

sysco.no

Sample XML Reference

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

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

sysco.no

REST Support in Oracle PaaS

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

sysco.no

REST Support in Java EE

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»

sysco.no

Java EE/RAML Sample

sysco.no

Java EE/RAML Sample

sysco.no

Java EE/RAML Sample

sysco.no

Q & A

sysco.no

Enjoy the AMIS conference!

SYSCO 2016