SOAP, REST and GraphQL

Design Strategies and Pitfalls

Who am I?

José Rodrigues

* at Link Consulting

What do I do?

• Technology and Cloud Strategist

• Cloud Architect

• OUGPT Leader

• Speaker at Tech Events

• Programmer as a Hobby (YEAAH!)

Recommended Book

API’s – The Door

Caroline Sanstead @ Flickr.com

https://www.flickr.com/photos/34085053@N08/

API’s – The Door

Caroline Sanstead @ Flickr.com

https://www.flickr.com/photos/34085053@N08/

Data

Functionality

Simple enough to screw up big time!

5 WE MANAGE KNOWLEDGE, WITH YOU

Main Pillars of API Initiatives

API

Management

API

Gateway

API

Portal

Management,

Strategy and

Governance

ExecutionCommunity

Engagement

1. Ease of use (1)

2. Performance (2)

3. Documentation (8)

4. Reliability (3)

5. Availability (4)

Most Important Factors in an API

https://static1.smartbear.co/smartbearbrand/media/pdf/smartbear_state_of_api_2019.pdf

Technologies

• SOAP (Protocol)

– Typically over HTTP, using XML

– Focus on Operations

Technologies

• SOAP is DEAD – REST in peace!

• REST (Arch. Style)

– Web Services that conform to REST are RESTful

– Run over HTTP, typically using JSON or XML

– Focus on Resources (URI)

Image from Fetching data from a REST API with React - Shivam Desai - Medium

Technologies

• SOAP is DEAD – REST in peace!

• REST is DEAD – Long Live GraphQL!

• GraphQL (Framework)

– Run over HTTP POST using JSON

– Focuses on Querys, Mutations and Subscriptions

(event driven)

– (Over/under)fetching, Composition, Strongly

Typed

linkconsulting.com

IF YOU USE POLYGLOT MICROSERVICES

WHY NOT USE A POLYTECH API

STRATEGY?

Unless you were born in the RESTful age...

Unless you were born in the RESTful age...

Api Design Strategies

API Design-First

• Defining the contract

– API Blueprint

– OpenAPI (ex-Swagger)

• Set a mock server

• Generate Stubs to

Accelerate Dev and

add common functions

* in “Implementing Oracle API Platform Cloud Service”, Andrew

Bell, Sander Rensen, Luis Weir, Phil Wilkins - Packtpub

Single Purpose vs Multi Purpose

• Open Modern Software Architecture

Project (http://OMESA.io)

Single Purpose vs Multi Purpose

• Multi Purpose

– Generic (not optimized)

– Information rich

– System-to-System focus

– Vs batching/bulk data

– Single domain

* in “Implementing Oracle API Platform Cloud Service”, Andrew

Bell, Sander Rensen, Luis Weir, Phil Wilkins - Packtpub

*

Single Purpose vs Multi Purpose

• Single Purpose

– Optimized for a purpose

• Reduced data size and

calls

– Typically on-top-of

Multi purpose APIs

– Multiple Domain

* in “Implementing Oracle API Platform Cloud Service”, Andrew

Bell, Sander Rensen, Luis Weir, Phil Wilkins - Packtpub

*

API Development

APIs are not about the Tooling

• Too much care on implementation aspects,

not enough focus on the actual API usage

• Some Devs tend to go after the next best

coolest thing in IT (coolness factor)

• Some Devs tend to use whatever they use

for ages (comfort factor)

• Focus on Design First, only then on

implementation

API Sandwich Pattern

• Layers and Layers of middleware, without

any real tangible benefit

• Quest for Abstraction and

patternization

• API Infrastructure limited

use

• API’s should be lean and

meanImage by @LuisW19, based on an image by Rick Charles

https://rickmc.files.wordpress.com/2010/11/gluttony.jpg

API Gateway Pattern

• Domain Driven Design principles

• Single Purpose (BFF), Protocol Conversion,

Composition, etc..

Images from http://microservices.io

API Gateway Pattern

• Service Mesh as an alternative to API

Gateway Layers

Images from https://medium.com/microservices-in-

practice/service-mesh-vs-api-gateway-a6d814b9bf56 , Kasun

Indrasiri

- Circuit

Breakers,

time-outs or

Load

Balancing

+ Service

Discovery,

Observability

, Health

recovery

The Chatty API

• Network traffic hogging

• Hundreds of calls, simply to build a page

– Typically because of too granular resources

• Too slow of an experience, extremely

expensive

• The use of frameworks without actually

knowing what’s going on behind the scenes.

Reduce your network traffic

• Async integration patterns

– Webhooks pub/sub

• API Composition with good caching

strategies (multi purpose + single

purpose)

• Continuous monitoring of your network

calls and optimize (Browser Dev Tools are

your friends!)

Document your API

• Your API is only as good as its ease of

use.

– An undocumented API, or even worse, a poorly

documented API is S#$T!

• Don’t rush your deployment

• Use the API Design first approach!

– Even on revisions!

API Documentation Cheat Sheet

Image by @LuisW19 – The 7 Deadly Sins of API Design,

Devoxx UK 2019

RESTful APIs != HTTP APIs

• HTTP is a transport protocol!

• You do SOAP over HTTP, you do REST over

HTTP, you can use JSON with SOAP and XML

with REST

• REST is an architectural style

• People tend to use “REST” without knowing

what REST is…

– Roy Fielding’s PhD thesis that defines REST:

https://www.ics.uci.edu/~fielding/pubs/disserta

tion/top.htm

REST Maturity Model

• #1 Fail - No

HATEOAS

(Hypermedia As

The Engine Of

Application

State)!

• Design your API

to be self-driven

https://martinfowler.com/articles/richardsonMaturityModel.html

Know thy REST Architectural Principles

• Don’t put operations in URI’s

– Let the HTTP verb decide the operation Print

this! https://github.com/jesusabdullah/know-your-

http/blob/master/methods.pdf?raw=true

• Don’t mix resources names cardinality:

– “order” and “orders”

– Use plurals as a best practice

• Proper use of HTTP Status Codes:

– POST with a 200 OK? Print this!

https://github.com/jesusabdullah/know-your-

http/blob/master/status-codes.pdf?raw=true

Know thy REST Architectural Principles

• Control the data being returned

– [GET] http://www.amazon.com/v1/APIs/customers

<- returns 2.000.000.000 customers’ data

– Use limits and offsets

Example HATEOASGET /accounts/12345/

HTTP/1.1

Host: bank.example.com

Accept: application/xml

Example HATEOASGET /accounts/12345/

HTTP/1.1

Host: bank.example.com

Accept: application/xml

HTTP/1.1 200 OK

Content-Type: application/xml

Content-Length: ...

<?xml version="1.0"?>

<account>

<account_number>12345</account_number>

<balance currency="usd">100.00</balance>

<link rel="deposit" href="/accounts/12345/deposit" />

<link rel="withdraw" href="/accounts/12345/withdraw" />

<link rel="transfer" href="/accounts/12345/transfer" />

<link rel="close" href="/accounts/12345/close" />

</account>

Example HATEOASGET /accounts/12345/

HTTP/1.1

Host: bank.example.com

Accept: application/xml

HTTP/1.1 200 OK

Content-Type: application/xml

Content-Length: ...

<?xml version="1.0"?>

<account>

<account_number>12345</account_number>

<balance currency="usd">100.00</balance>

<link rel="deposit" href="/accounts/12345/deposit" />

<link rel="withdraw" href="/accounts/12345/withdraw" />

<link rel="transfer" href="/accounts/12345/transfer" />

<link rel="close" href="/accounts/12345/close" />

</account>

After withdrawing

125 USD

Example HATEOASGET /accounts/12345/

HTTP/1.1

Host: bank.example.com

Accept: application/xml

HTTP/1.1 200 OK

Content-Type: application/xml

Content-Length: ...

<?xml version="1.0"?>

<account>

<account_number>12345</account_number>

<balance currency="usd">100.00</balance>

<link rel="deposit" href="/accounts/12345/deposit" />

<link rel="withdraw" href="/accounts/12345/withdraw" />

<link rel="transfer" href="/accounts/12345/transfer" />

<link rel="close" href="/accounts/12345/close" />

</account>

After withdrawing

125 USD

Example HATEOASGET /accounts/12345/

HTTP/1.1

Host: bank.example.com

Accept: application/xmlHTTP/1.1 200 OK

Content-Type: application/xml

Content-Length: ...

<?xml version="1.0"?>

<account>

<account_number>12345</account_number>

<balance currency="usd">-25.00</balance>

<link rel="deposit" href="/accounts/12345/deposit" />

</account>

HTTP/1.1 200 OK

Content-Type: application/xml

Content-Length: ...

<?xml version="1.0"?>

<account>

<account_number>12345</account_number>

<balance currency="usd">100.00</balance>

<link rel="deposit" href="/accounts/12345/deposit" />

<link rel="withdraw" href="/accounts/12345/withdraw" />

<link rel="transfer" href="/accounts/12345/transfer" />

<link rel="close" href="/accounts/12345/close" />

</account>

After withdrawing

125 USD

HTTP/2 – a giant leap in performance

• Request/Response Multiplexing A lot of

requests from a single connection

• Server Push Servers proactively push

resources to the client, without them

requesting

– Define linked resources Vulcain

• Is GraphQL Dead? https://github.com/dunglas/vulcain

With Distributed computing, comes Async APIs

• Webhooks

• WebSockets

• gRPC

• GraphQL Subscriptions

• GraphQL Live Queries

Special Thanks to Luis Weir

• @Luisw19 on twitter

• I’m a disciple of Luis’ approach to API

Design and Development Practices

• Check his blog: http://www.soa4u.co.uk

• Follow him on Twitter. He’s a frequent

poster!

Questions?

linkconsulting.com

COMPARISON ON REST VS GRAPHQLBy Luis Weir and James Neate

GraphQL vs REST

Graph by @LuisW19 and @jmneate – GraphQL as an

alternative to REST

GraphQL vs REST

Graph by @LuisW19 and @jmneate – GraphQL as an

alternative to REST