Building Your API for Longevity

transcript

Building Your API for Longevityby mike stowe

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.

Disclaimer

• API Fanatic

• Open Source Contributor

• Author, Speaker, Consultant

• 10+ years hacking Professional Code

• Dev Relations Manager at MuleSoft

About Me

APIs are changing the world.

Over 13,000 PUBLIC APIs

Today APIs are connecting…

PHONES

WATCHES

GLASSES

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.

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

They are:

• 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

Think Long-term:

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.

Your Users are Depending on You…

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

•  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?

Thinking things through…

•  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.

Who Will Be Using 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.

What is the Purpose of Your API?

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

•  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?

•  Client-Server

•  Stateless

•  Cacheable

•  Interface/ Uniform Contract

•  Layered System

•  Code on Demand (optional)

Do You Understand the REST Constraints?

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.

•  Backwards incompatibilities

•  Multiple Services to Maintain

•  Multiple Systems to Support

•  Creates confusion among developers

•  Developer adoption is nearly impossible

Problems with Versioning

•  Backwards incompatible platform changes

•  Your API is no longer extendable

•  Your spec is out dated (ie SOAP)

You Need to Version When:

•  Added new endpoints

•  Added additional data in response

•  Changed technologies (java toruby)

•  Changed your application’s services (code)

But You Shouldn’t Version Just Because You:

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.

• 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!

Use Spec Driven Development

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.

•  RAML

•  IO Docs

•  Swagger

•  API Blueprint

Some of Today’s Specs:

•  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)

Using RAML You Can:

•  You can use design patterns

•  You can reuse code (traits, resourceTypes)

More Importantly…

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.

• Use Nouns

• Use CRUD

• Use Hypermedia (HATEOAS)

• Use Accept/ Content-Type

• Return Header Codes

• Return Descriptive Error Messages

Incorporate Best Practices:

Use Nouns.

/users Not:

/createUser /getUser /deleteUser

Utilize CRUD.

Create (POST)

Read (GET)

Update (PUT/ PATCH)

Delete (DELETE)

Use Hypermedia.HATEOAS

•  HAL

•  JSON-LD

•  JSON API

•  Siren

Building Your API for Longevity

Technology