There is no doubt that Web APIs have become a fundamental aspect of modern architectures. However how to distinct a “good” API from an “evil” one is a topic for debate and one that often ends up in a “religious” debate. However, the one thing that is clear to most people, is that it all starts with a design, and getting that design right up-front will likely result in less headaches down the line. So how to avoid “evil” APIs? In this presentation, I will talk about the 7 most common pitfalls I’ve come across when doing API design in large implementations. With real-life examples, I will describe why such pitfalls deserved to be called “evil” and how to remediate them with “good" design practices. The presentation will also touch upon how API-design first techniques can be applied to solve prevent some of the common issues. It will be a highly interactive session with good balance of theory and practice.

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

2. 2THE 7 DEADLY SINS OF {API} DESIGN @LUISW19
ABOUT ME

3. 3THE 7 DEADLY SINS OF {API} DESIGN @LUISW19
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

4. 4THE 7 DEADLY SINS OF {API} DESIGN @LUISW19
THE 7 DEADLY SINS
1- LUST
Unrestrained
desire for
something
Try
this
tool

5. 5THE 7 DEADLY SINS OF {API} DESIGN @LUISW19
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?

6. 6THE 7 DEADLY SINS OF {API} DESIGN @LUISW19
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

7. 7THE 7 DEADLY SINS OF {API} DESIGN @LUISW19
THE 7 DEADLY SINS
2- GLUTTONY
The over-
indulge
specially by
over eating

8. 8THE 7 DEADLY SINS OF {API} DESIGN @LUISW19
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à

9. 9THE 7 DEADLY SINS OF {API} DESIGN @LUISW19
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

10. 10THE 7 DEADLY SINS OF {API} DESIGN @LUISW19
THE 7 DEADLY SINS
3- GREED
Intense and
selfish desire
for something

11. 11THE 7 DEADLY SINS OF {API} DESIGN @LUISW19
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

12. 12THE 7 DEADLY SINS OF {API} DESIGN @LUISW19
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

13. 13THE 7 DEADLY SINS OF {API} DESIGN @LUISW19
THE 7 DEADLY SINS
4- SLOTH Laziness, lack
of effort

14. 14THE 7 DEADLY SINS OF {API} DESIGN @LUISW19
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?

15. 15THE 7 DEADLY SINS OF {API} DESIGN @LUISW19
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…

16. 16THE 7 DEADLY SINS OF {API} DESIGN @LUISW19
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]

17. 17THE 7 DEADLY SINS OF {API} DESIGN @LUISW19
THE 7 DEADLY SINS
5- WRATH
Uncontrolled
feelings of
hatred and
anger

18. 18THE 7 DEADLY SINS OF {API} DESIGN @LUISW19
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

19. 19THE 7 DEADLY SINS OF {API} DESIGN @LUISW19
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

20. 20THE 7 DEADLY SINS OF {API} DESIGN @LUISW19
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/#

21. 21THE 7 DEADLY SINS OF {API} DESIGN @LUISW19
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.

22. 22THE 7 DEADLY SINS OF {API} DESIGN @LUISW19
THE 7 DEADLY SINS
6- ENVY
Jealousy
towards
another's
happiness

23. 23THE 7 DEADLY SINS OF {API} DESIGN @LUISW19
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}

24. 24THE 7 DEADLY SINS OF {API} DESIGN @LUISW19
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

25. 25THE 7 DEADLY SINS OF {API} DESIGN @LUISW19
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"
}
]
}
}

26. 26THE 7 DEADLY SINS OF {API} DESIGN @LUISW19
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

27. 27THE 7 DEADLY SINS OF {API} DESIGN @LUISW19
THE 7 DEADLY SINS
7- PRIDE
Inflated sense
of one's
accomplishments

28. 28THE 7 DEADLY SINS OF {API} DESIGN @LUISW19
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!

29. 29THE 7 DEADLY SINS OF {API} DESIGN @LUISW19
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.

30. 30THE 7 DEADLY SINS OF {API} DESIGN @LUISW19
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