Build APIs for Longevity with Spec Driven Development

Building Your API
for Longevity
by mike stowe
l All contents Copyright © 2014, MuleSoft Inc.

Disclaimer
This talk is not about how to code your
API, but rather to show you what steps and
best practices you need to utilize to build
a successful, long-lived API to the extent
that we can in 45 minutes.

About Me
• API Fanatic
• Open Source Contributor
• Author, Speaker, Consultant
• 10+ years hacking Professional Code
• Dev Relations Manager at MuleSoft

APIs are changing the
world.

Over 13,000 PUBLIC APIs

Today APIs are connecting…

PHONES

WATCHES

GLASSES

CARS

REFRIGERATORS

THERMOSTATS

IN HOME
ROBOTS

AND MORE

THINK ABOUT THAT…

In order to work, the IoT
requires that APIs remain
persistent.

+

Versioning and making
changes is expensive…

FOR EVERYONE.

Thankfully with 5 Simple
Steps you can build an API
that is designed to last.

They are:
1 – Go in with a long-term mindset
2 – Understand what you’re building
3 – Utilize Spec Driven Development
4 – Incorporate Best Practices
5 – Repeat steps 1-4 for all new features

Think Long-term:
• Your API is a Contract
• Versioning is not a solution
• Understand you suck at design
• You can pay a little now, or much more later
• You need to think things through
• Mind-set is everything

Your Users are Depending on You…
Your API is a contract, it’s your word to
your users. Users who are not only
depending on a working API to integrate
with your service, but in order to provide
food for their families.
l All contents Copyright 24 © 2014, MuleSoft Inc.

This means you need to think through every
aspect of your API before building it.

Thinking things through…
• Who is your API for?
• What type of API are you building?
• How are you going to maintain your API?
• How are you going to document your API?
• How are you going to let users interact with your API?
• How are you going to manage authentication,
provisioning, throttling, and developer security?
• How are you going to protect your servers against
attacks, developer misuse, etc?
• How are you going to manage support?

Who Will Be Using Your API?
• Who are your end users?
- Current customers
- Business partners
- Third-party services
• What actions do they need access to?
- This means sitting down and talking to them!
• How can you involve them in the design process?
- Your users should be involved from Day One.

What is the Purpose of Your API?
• List out WHY you are making the API
- Saying that you’re exposing your data to users is not
good enough- explain HOW they will use it
• Explain how your API will interact with existing
services
• List out the actions the API needs to be able to handle
- Users: add, edit, reset password, delete, etc…
- Messages: draft, send, retrieve, archive, etc…
• Do only what is NECESSARY
• DON’T get fancy.

List Out What Your Users Need to be able to Do:

What Type of API Are You Building?
• Are you building a REST, partial REST, SOAP, or RPC
based API?
• Why are you building your API in that format?
• What does that mean for development?
• What does that mean for usability?
• What does that mean for longevity?

What Type of API Are You Building?

Do You Understand the REST Constraints?
• Client-Server
• Stateless
• Cacheable
• Interface/ Uniform Contract
• Layered System
• Code on Demand (optional)

Most APIs are NOT RESTful.

This is why it’s so important to understand
the different types of APIs, why each type is
different, and why you are choosing one
over the other.

It also means building your API for beyond
today…

...people are fairly good at short-term
design, and usually awful at long-term
design.”
“
-Dr. Roy Fielding

Versioning is a necessary evil.

Problems with Versioning
• Backwards incompatibilities
• Multiple Services to Maintain
• Multiple Systems to Support
• Creates confusion among developers
• Developer adoption is nearly impossible

You Need to Version When:
• Backwards incompatible platform changes
• Your API is no longer extendable
• Your spec is out dated (ie SOAP)

But You Shouldn’t Version Just Because You:
• Added new endpoints
• Added additional data in response
• Changed technologies (java toruby)
• Changed your application’s services (code)

Versioning does not excuse poor design.

And a poorly designed API will cost you far
more in the long run, adding months to fix what
could have been prevented in weeks. There are
no shortcuts or quick fixes, you can either build
your API the right way to begin with, or pay
substantially for it in the long-run.

Use Spec Driven Development
• Define your API before Coding
• Use Design Patterns/ Code Reuse
• Mock and get User Feedback
• Make Necessary Changes
• Start Coding – to the Spec
• DO NOT DEVIATE!

Spec Driven Development means a hybrid
between agile and waterfall methodologies.
You should develop your spec iteratively,
incorporating agile user testing. However,
the actual development (coding) of your API
should be static, driven by the spec with no
deviation.

Disclaimer: Waterfall refers to the spec and
changing the spec only! You should still use
sprints for code development – just at this
point the spec should not be changing.

Hybrid Approach
Design Development
Continuous, fluid, changeable Static… No turns

The Agile Design Cycle

The goal is that by utilizing agile user
testing, carefully designing, and
prototyping your API in an iterative state,
that most design related issues have
already been discovered and resolved.
Allowing you to develop fearlessly.

The problem is up until now, designing and
prototyping an API has been extremely
costly. Requiring developers to create a
mock API through extensive coding, and
without any real constraints/ pattern reuse.

However, there are several new specs being
driven by today’s industry leaders making it
easier define your API: with tools to design,
prototype, document, and allow user
interaction.

Some of Today’s Specs:
• RAML
• IO Docs
• Swagger
• API Blueprint

Using RAML You Can:
• You can define your API in just a few lines of code
• You can see what it would look like as you go
• You can quickly prototype it for devs to try
• You can quickly make tweaks/ changes
• You can easily document your API
• You can let developers try your API online
• You can let developers interact with your and other APIs
• Generate SDKs/ client libraries for your API (APIMatic.io)

More Importantly…
• You can use design patterns
• You can reuse code (traits, resourceTypes)
resourceTypes:
-‐
collection:
description:
Collection
of
available
<<resourcePathName>>
in
Jukebox.
get:
description:
Get
a
list
of
<<resourcePathName>>.
responses:
200:
body:
application/json:
example:
|
<<exampleCollection>>

The RAML API Designer

What Does RAML Look Like?
#%RAML
0.8
title:
World
Music
API
baseUri:
http://example.api.com/{version}
version:
v1
/playlists:
get:
responses:
200:
body:
application/json:
example:
|
{
“playlistID”
:
1,
“playlistName”
:
“My
Awesome
Playlist”,
“genre”
:
“top40”,
“songs”
:
40
}

Remember, your spec is not a one-and-done,
rather it is the blueprint for your API.
Anytime you do something to your API you
should be modifying the spec and going
through user testing before writing code.
You should never have code that does
something not defined by your spec.

Incorporate Best Practices:
• Use Nouns
• Use CRUD
• Use Hypermedia (HATEOAS)
• Use Accept/ Content-Type
• Return Header Codes
• Return Descriptive Error Messages

Use Nouns.

Use:
/users
Not:
/createUser
/getUser
/deleteUser

Utilize CRUD.

Create (POST)
Read (GET)
Update (PUT/
PATCH)
Delete (DELETE)

Use Hypermedia.
HATEOAS

Most Popular Hypertext Link Specs
• HAL
• JSON-LD
• JSON API
• Siren

{
"data"
:
{
"user":
{
"fname":"first",
"lname":"last"
}
},
"_links"
:
{
"edit":
{
"href"
:
"/api/user/id/1"
},
"message":
{
"href"
:
"/api/message/id/1/lname/last"
}
}
}
HAL

Use Accept/ Content-Type
Headers.

Use Accept/ Content-Type Headers
Using headers gives you flexibility to support multiple
types of formats from the same resource without
worrying about breaking backwards compatibility.
Most common:
• application/json - wider language support
• application/xml

Use Response Codes.

• 200 – OK
• 201 – Created
• 304 – Not modified
• 400 – Bad Request
• 401 – Not Authorized
• 403 – Forbidden
• 404 – Page/ Resource Not Found
• 405 – Method Not Allowed
• 415 – Unsupported Media Type
• 500 – Internal Server Error

Or if you’re feeling super creative…
• 418 – I’m a Teapot…
• 420 – Enhance Your Calm

Use Descriptive Error Messages.

The more information you provide, the easier it will be
for developers to integrate your API without contacting
Support.
{
'exception'
{
'code'
:
'e3526',
'message'
:
'Missing
UserID',
'description'
:
'A
UserID
is
required
to
edit
a
user.',
'link'
:
'http://docs.mysite.com/errors/e3526/'
}
}

Also be sure to keep your documentation up
to date and simple enough for developers to
quickly find and implement solutions to
even the most complex problems. Poor
documentation has been the death of many
an API.

Finally, when adding new things
to your API, be sure to:

Finally, when adding new things
to your API, be sure to:
1 – Go in with a long-term mindset
2 – Understand what you’re building
3 – Utilize Spec Driven Development
4 – Incorporate Best Practices

It only takes ONE little thing to significantly
reduce your API’s life span. Every action you
make on your API must be carefully thought
out and tested BEFORE being pushed to
production.

Remember...

Building an API is easy.

Designing an API is hard.

Build APIs for Longevity with Spec Driven Development

Recommended

Recommended

More Related Content

What's hot

What's hot (18)

Similar to Build APIs for Longevity with Spec Driven Development

Similar to Build APIs for Longevity with Spec Driven Development (20)

More from MuleSoft

More from MuleSoft (20)

Recently uploaded

Recently uploaded (20)

Build APIs for Longevity with Spec Driven Development