5 Golden Rules to Building APIs

simple software solutions to big business problems
Making Software. Better.
Digital By Default
Building APIs for the Government

2
I believe the creation of the Government
Digital Service is one of the great unsung
triumphs of the last Parliament.
Prime Minister David Cameron

A barrier to innovation
3
SOAP-based proprietary webservices, which
software vendors currently integrate with, are
cumbersome, poorly documented and a disservice
to us, the taxpayer

Brave New World
By creating a new API platform built upon user
needs, based on RESTFul principles, we have
reduced the barrier to entry and innovation.

10 Years of AWS - APIs are forever
“.......Once customers started building their
applications and systems using our APIs, changing
those APIs becomes impossible, as we would be
impacting our customer’s business operations if we
would do so. We knew that designing APIs was a
very important task as we’d only have one chance
to get it right.”
http://www.allthingsdistributed.com/2016/03/10-lessons-from-10-years-of-aws.html

5 Golden RulesOf Building APIs at HMRC Digital

Secure, performant and easy
An API platform is not fit for purpose unless it is
secure, handles appropriate throughput accurately,
is easy to integrate with and is easy to publish and
document

Protect your platform
Throttling is an important part of any API platform
but shouldn’t be seen as a backup option for a
poorly performing API, but as protection against
poorly written/abusive 3rd party software.

Plan for change
Define a versioning strategy early, one that fits your
architecture, organisation and clients. Make
backward compatibility a key goal.

Golden Rule 2
If you can’t make it good, at least make it look good - Bill Gates
Make it Beautiful

Importance of beautiful APIs
12
APIs are the public face of your IT. They are part
of your brand, reputation and an insight into
your quality. You wouldn’t deliver an ugly
website.

Golden Rule 3
Focus your APIs on your domain, not your offline processes
Change your perspective

Why not business processes?
Business processes were not created for the
digital world. They were created for cryptic
commands into mainframe terminals, paper
forms and human (intelligent) intervention.
Reflect these digitally and you limit APIs

Domain not processes
Create APIs that reflect your domain, using
Domain Driven Design concepts. You will not
limit yourselves to existing processes, you’ll
hide the implementation and you’ll use industry
language. In so doing, complexity is removed.

How have we changed our focus?
16
HMRC is traditionally siloed along the lines of
tax regimes. Code, systems, people, databases.
Tax regimes are the processes, not the domain.
The digital world reflected the offline. We’ve
changed our focus. Our APIs will be domain
centric and not regime centric.

Golden Rule 4
REST only has one level; Anything else is not REST
Use Hypermedia

Richardsons Maturity Model
Courtesy of www.
martinfowler.com

Why we should stop talking about it
Richardson’s Maturity Model has become a
justification to not use Hypermedia. It is not
meant to be a model for levels of valid REST
development. Just an observation of an
organisation’s proximity to REST

No Hypermedia, No REST
“If the engine of application state (and hence
the API) is not being driven by hypertext, then
it cannot be RESTful and cannot be a REST API.
Period.” - Roy Fielding

What is Hypermedia (HATEOAS)
{
self: {
url: “http://api.reda.com/users/reda”
},
data: {
name: “Reda Hmeid”,
age: “23”,
height: “6ft 2in”,
address_url: “http://api.reda.com/users/reda/addresses”,
messages_url: “http://api.reda.com/users/reda/messages”
},
links:[
{
url: “http://api.reda.com/users/reda/messages”,
rel: “Send a new message”,
method: “Post”
},
{
url: “http://api.reda.com/users/reda”,
rel: “Update details”,
method: “Put”
}
]
}

What does Hypermedia provide
By controlling flow and business logic within
the API, thereby hiding implementation, you
ensure loose coupling between the client and
the API. This allows for more frequent
impactless changes and added functionality.

But also
Hypermedia reduces latency and reduces load
on the server. Clients can be much dumber,
needing less business code, making it cheaper
to produce software.

Golden Rule 5
Your organisation is mature enough to build RESTFul APIs today
You’re Ready

You can maintain the status quo
Or you can make things better. Maturity of an
organisation is where it is now. Not where it can be
and what it can do.

Examples of the Good
Proof that beautiful APIs are “pragmatic” APIs

● Github.com
https://developer.github.
com/v3/pulls/
● Stormpath.com
https://docs.stormpath.
com/rest/product-
guide/latest/reference.
html#application
● Paypal.com
https://developer.paypal.
com/docs/rest/api/
● Visa
https://developer.visa.com
Examples

References
Want to learn more; try these

1. Rest in Practice - Jim Webber
2. Domain Driven Design - Eric Evans
3. RESTFul Web Services Cookbook - Subbu Allamajru
4. http://martinfowler.com/articles/richardsonMaturityModel.html

Thank You
Twitter
@EqualExperts
LinkedIn
linkedin.com/company/equal-experts
UNITED KINGDOM
+44 203 603 7830
helloUK@equalexperts.com
Equal Experts UK Ltd
30 Brock Street
London NW1 3FG
INDIA
+91 20 6607 7763
helloIndia@equalexperts.com
Equal Experts India Private Ltd
Office No. 4-C
Cerebrum IT Park No. B3
Kumar City, Kalyani Nagar
Pune, 411006
Web
www.equalexperts.com
CANADA
+1 403 775 4861
helloCanada@equalexperts.com
Equal Experts Devices Inc
205 - 279 Midpark way S.E.
T2X 1M2
Calgary, Alberta
Twitter:
@softwarereda
LinkedIn:
linkedin.com/in/redahmeid

5 Golden Rules to Building APIs

More Related Content

What's hot (20)

Viewers also liked (20)

Similar to 5 Golden Rules to Building APIs (20)

Recently uploaded (20)

5 Golden Rules to Building APIs