The 7 Deadly Sins of API Design

1THE 7 DEADLY SINS OF {API} DESIGN @LUISW19
DEADLY SINS
OF {API} DESIGN
THE

ABOUT ME

LUIS WEIR
CTO Capgemini UK Oracle
Groundbreaker Ambassador & Ace Director
luis.weir@capgemini.com
uk.linkedin.com/in/lweir
@luisw19
http://www.soa4u.co.uk
tinyurl.com/eapim18
Q2 2019
apiplatform.cloud/
May 2018
ABOUT ME

THE 7 DEADLY SINS
1- LUST
Unrestrained
desire for
something
Try
this
tool

1- LUST: The Perfectly Useless API
Focusing mainly on runtime,
implementation tech, CICD
(e.g. K8s, APIG, APIMGW,
Mesh, Pipelines, etc) and
forgetting about the API
usability.
The motivations:
Typically:
• Fashion,
• CV building,
• Comfort zones,
• Even office politics?

1- LUST: Deliver us from evil
API design first, implementation
second. It doesn’t take fancy
tools or complex steps to do
this:
1. First capture what the needs
really are in a design,
2. Quickly mock API endpoints,
share, get feedback,
3. Once design is complete,
ensure implementation
consistency by testing design
against service.
Design Build &
Test
Try
01
• API docs and mock
endpoints available
in the Dev Portal
• API consumers try the
API and give feedback
02 03
Feedback-loops

THE 7 DEADLY SINS
2- GLUTTONY
The over-
indulge
specially by
over eating

2- GLUTTONY: The API Sandwich Architecture
Purposely adding layers on top of
layers of API middleware unnecessarily
adding complexity and costs without
clear business benefits. ßBackend for
Frontend
API Consumerà
ß Service
The motivations:
There are many but commonly:
• In the name of abstraction and
decoupling??
• Unawareness of, or avoidance to use,
existing API infrastructure,
• Solving a network problem (e.g. geo-
routing)
• Other sins? e.g. envy, pride?.
LBà
ßInternal API
Gateway
ßAPI Micro-
Gateway
LBà
LBà
LBà

2- GLUTTONY: Deliver us from evil
Remove unnecessary layers by:
1. Seriously questioning what is
unique value each layer adds
2. Adopt domain-driven design
principles. Get the bounded
contexts right,
3. Consider a service mesh instead
more layers of API Gateways (or
event sourcing),
4. Checkout API Gateway Pattern.
API Consuming Applications
Customers
Service
Orders
Service
Logistics
Service
Service
Registry
Frontend
Specific
Service
API Gateway
Backend
Frontends
Service
M
esh
discovery
discovery

THE 7 DEADLY SINS
3- GREED
Intense and
selfish desire
for something

3- GREED: The Chatty API
Abusive use of network resources
resulting in bad API consumption
experience:
1. A client application has to make
several API calls just to build up
a single page,
2. HTTP GET as a strategy to do batch
data downloads.
The motivations:
• Selfishness: I’ve built my APIs, it’s
up to the UI how to use it
• Easier to extend an existing API with
e.g. pagination, HTTP chunking, etc.
APIGateway
++ bandwidth = $$ & << UX

3- GREED: Deliver us from evil
Optimise number of API calls by
adopting a different approach:
1. Webhooks as means to
implement web events (push
not pull –only send data
changes)
2. Implement an API Composition
pattern (e.g. consider
GraphQL?)
APIGateway
EventHub
APIGateway
API Composition
Webhooks
subscribe
Web events
Composition
Service

THE 7 DEADLY SINS
4- SLOTH Laziness, lack
of effort

4- SLOTH: REST In Peace (RIPfull)
Ignoring REST architectural principles. E.g.:
• Operations in URIs:
[GET] https://eg.com/getAllorders
[GET] https://eg.com/getOrder?id=xxx
[POST] https://eg.com/newOrder
[PUT|DELETE] https://eg.com/updateOrder?id=xxx
• Unbounded responses?
[GET] https://eg.com/orders àso, send back 1m orders?
• Use of both singulars and plurals in a single API
[GET] https://eg.com/orders
[GET] https://eg.com/order/1234
• Ignoring HTTP status codes
[POST] https://eg.com/orders
{…}
Response:
HTTP 200 Ok à Really?

4- SLOTH: REST In Peace (RIPfull)..continues
• Go figure out how to find a related
resource
[GET] https://eg.com/orders
[orders{
order:{
"id":"or001",
customer: {
"id":"cust123" à where is it?
}
},
…
}]
The motivations:
Still a mystery to me… but perhaps:
• Using SOAP to REST convertors?
• Lack of understanding of REST?
• Or simply SLOTH…

4- SLOTH: Deliver us from evil
Lots of content online for best practices..
So no excuse Homer. In any case:
• Use HTTP verbs
Search, Create: [GET|POST] /orders?{search filters}
Read, Update, Partly update, Remove:
[GET|PUT|PATCH|DELETE] /orders/{id}
• Plural nouns are best (see above)
• Use limits/offsets to constraint response
/orders?limit=50&offset=150&{additional filters}
• Respect HTTP status codes e.g.
2xx – Success, 4xx – Client errors, 5xx – Server errors. à check this link
• HATEOAS unless impossible. Check Richardson’s maturity model
• Idempotency on methods: [GET|PUT|PATCH|DELETE]

THE 7 DEADLY SINS
5- WRATH
Uncontrolled
feelings of
hatred and
anger

5- WRATH: No (documented?) API
What can be worse than not having
an API? Well, an undocumented API
or even worse, a poorly documented
API…
The motivations:
Most likely:
• An accidental API (those that
weren’t meant to used but sort
of did),
• Time pressures (deadlines),
• Other sins .. Sloth
My API Doc

5- WRATH: Deliver us from evil
An API is only as good
as its doc.
The ABC of a Good API:
• Absent API doc =
No API,
• Bad documentation =
Angry Developers,
• Can’t find it =
re-inventing wells
(duplicate APIs)
A good API Doc should include
API Page
(e.g. doc.myapi.com)
Nav: Get Started
Intro
Authentication
Errors
Constraints
Change Log
Resource Name
Nav: Resources
Resource Name
Search
Create
Read
Update
Delete
Curl JS | Java |..
API Mock URL
Sample Requests
URI / Params
description
Sample Responses
Description of
resource. What
is it? What
does it do?
GET /samples?{}
Description of
the endpoint.
Search
POST /samples
Description of
the endpoint.
Create
Resource Name

5- WRATH: Deliver us from evil
An API is only as good
as its doc.
The ABC of a Good API:
• Absent API doc =
No API,
• Bad documentation =
Angry Developers,
• Can’t find it =
re-inventing wells
(duplicate APIs)
https://ordersms.docs.apiary.io/#

5- WRATH: Recommend
Good examples of API docs:
• Stripe API: https://stripe.com/docs/api
• Strava API: https://developers.strava.com/docs/reference/
Some good tools:
• Apiary.io: supports OAS, API Blueprint, rich documentation,
Mocking server, spec testing with Dredd,
• Swagger.io: full API design lifecycle for OAS,
• RedDoc: generates responsive web apps from OAS specs.
• Snowboard & Aglio: really nice API blueprint
parsers/renderers.

THE 7 DEADLY SINS
6- ENVY
Jealousy
towards
another's
happiness

6- ENVY: The Disloyal API Designer
So you’re a REST fan. Considering GraphQL as an
alternative it’s just unconceivable. Even if UI
developers favour it.
The motivations:
Multiple valid reasons:
• Existing investment in REST
APIs,
• Current skills in the
organisation,
• Reluctance to change?
• Other since: Pride?
{REST}

Let’s put it into perspective
https://trends.google.com/trends/explore?date=2004-01-10%202018-10-01&q=GraphQL,REST%20API,OData,WSDL
WSDLGraphQL REST API OData
Feb 2004 Oct 2018

6- ENVY: Deliver us from evil
GraphQL IS NOT a silver bullet. But it has some
great features:
• Best for API usability (specially with
GraphiQl, get only the data you want),
• Best for API composition pattern,
• It can perfectly co-exist with REST. REST REST REST
API
GraphQL
Define Schema
type Country {
id: ID!
name: String!
code: String!
}
type query {
countries:
[Country]
}
GraphQL Service GraphQL Client
Quickly write and
run queries
{
getCountries(name:"great")
{
name
}
}
GraphQL Client
Get exactly what
you asked for
{
"data": {
"countries": [
{
"name": "United
Kingdom"
}
]
}
}

6- ENVY: Recommend
Browser
GraphiQL
{
query
}
GraphQL Server:
Apollo/Express
GraphQL Service
Graphiql
GraphQL Schema
GraphQL Endpoint
Query Operation {JSON}
[HTTP/POST]
{JSON}
{
data
}
[HTTP/GET]
https://restcountries.eu/rest/v2/{resource}
{JSON}
REST COUNTRIES
[HTTP/POST]
https://www.google.co.uk/search?q={search}
{JSON}
• Devoxx London: GraphQL as an alternative approach to REST,
• 4 part code samples:
https://github.com/luisw19/graphql-samples

THE 7 DEADLY SINS
7- PRIDE
Inflated sense
of one's
accomplishments

7- PRIDE: Bottom-up API Design
Unanimously deciding what the
interface should be. No design
feedback loops.
The motivations:
Most likely:
• Easier/quicker to auto-generate
endpoints from data sources,
• Time pressures (deadlines),
• Or just Pride!

7- PRIDE: Deliver us from evil
No better accomplishment as an
API designer/developer to create
an API that is actually used and
good feedback is received.
Avoid the picture on the rightà
Design your API first with
usability in mind.

This message contains information that may be privileged or confidential and is
the property of the Capgemini Group.
Copyright © 2018 Capgemini. All rights reserved.
A global leader in consulting, technology services and digital transformation, Capgemini is
at the forefront of innovation to address the entire breadth of clients’ opportunities in the
evolving world of cloud, digital and platforms. Building on its strong 50-year heritage and
deep industry-specific expertise, Capgemini enables organizations to realize their business
ambitions through an array of services from strategy to operations. Capgemini is driven
by the conviction that the business value of technology comes from and through people.
It is a multicultural company of 200,000 team members in over 40 countries. The Group
reported 2017 global revenues of EUR 12.8 billion.
About Capgemini
Learn more about us at
www.capgemini.com

The 7 Deadly Sins of API Design

More Related Content

What's hot (17)

Similar to The 7 Deadly Sins of API Design (20)

More from luisw19 (7)

Recently uploaded (20)

The 7 Deadly Sins of API Design