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#DevoxxUk
DEADLY SINS
OF {API} DESIGN
THE

2. 2THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk
LUIS WEIR
Director Software Development
Oracle Hospitality
luis.weir@oracle.com
uk.linkedin.com/in/lweir
@luisw19
http://www.soa4u.co.uk
tinyurl.com/eapim19
July 2019
apiplatform.cloud/
May 2018
ABOUT ME @luisw19

3. 3THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk
This is an opinionated presentation
expressing my own views.

4. 4THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk
APIs are doors to information and functionality.

5. 5THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk
But if you get the design and implementation
wrong…
https://www.boredpanda.com/funny-architecture-construction-fails/?utm_source=google&utm_medium=organic&utm_campaign=organic

6. 6THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk
So avoid common API-design pitfalls by not
committing any of the 7 Deadly Sins
1- LUST
2- GLUTTONY
3- GREED
4- SLOTH
5- WRATH
6- ENVY
7- PRIDE

7. 7THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk
So avoid common API-design pitfalls by not
committing git commit(ing) any of these sins
1- LUST
2- GLUTTONY
3- GREED
4- SLOTH
5- WRATH
6- ENVY
7- PRIDE

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

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

10. 10THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk
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 &
Contract 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
inspector
OpenAPI-to-Postman

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

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

13. 13THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk
2- GLUTTONY: Deliver us from evil
Remove unnecessary layers by:
1. Seriously questioning what is
the 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
discovery
discovery

14. 14THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk
THE 7 DEADLY SINS
3- GREED
Intense and
selfish desire
for something
Derek Michael Brennan

15. 15THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk
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:
• HATEOAS to the extreme…
• Extremely granular resource designs
• Batch downloads via paginated payloads
APIGateway
++ bandwidth = $$ & << UX

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

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

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

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

20. 20THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk
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 (but not to the extream). Check Richardson’s maturity model
• Idempotency on methods: [GET|PUT|PATCH|DELETE]

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

22. 22THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk
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
API Doc
Angry developer Is this
supposed to
be an API
Doc?

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

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

25. 25THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk
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,
• Snowboard & Aglio: really nice API blueprint
parsers/renderers.

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

27. 27THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk
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?
https://imgur.com/a/J3ttg
{REST}

28. 28THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk
Let’s put it into perspective
https://trends.google.com/trends/explore?date=2004-01-10%202019-05-09&q=GraphQL,REST%20API,OData,WSDL
trend
WSDLGraphQL REST API OData
Feb 2004 May 2019

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

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

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

32. 32THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk
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!
http://www.constructionhunter.com.au/blog/industry-news/20-
photos-that-will-make-you-question-your-faith-in-humanity

33. 33THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk
7- PRIDE: Deliver us from evil
No better accomplishment as an
API designer/developer to create
an API that is fit for purpose
and actually used.
Avoid the picture on the right
Design your API first with
usability in mind.
https://www.pinterest.co.uk/pin/504543964485602355
https://www.boredpanda.com/funny-architecture-construction-
fails/?utm_source=google&utm_medium=organic&utm_campaign=organic

34. 34THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk
Questions?
A similar presentation is available at www.soa4u.co.uk :
www.soa4u.co.uk/2018/10/the-se7en-deadly-sins-of-api-design.html