soap, rest and graphql · restful apis != http apis • http is a transport protocol! • you do...
TRANSCRIPT
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