apis for microservices

l All contents Copyright © 2014, MuleSoft Inc.

APIs for Microservices

by mike stowe


• API Fanatic

• Open Source Contributor

• Author, Speaker, Consultant

• 10+ years hacking Professional Code

• Dev Relations Manager at MuleSoft

About Me

@mikegstowe


Why Microservices?

l All contents Copyright © 2014, MuleSoft Inc.4

• Business value over technical strategy

• Strategic goals over project-specific benefits

• Intrinsic interoperability over custom integration

• Shared services over specific-purpose implementations

• Flexibility over optimization

• Evolutionary refinement over pursuit of initial perfection

A Different Focus


• Values logical representations of a business activity with a specified outcome

• Is self contained/ autonomous

• May be composed of other services

• Is abstracted from consumers via an API

A Self-Contained, Composable, Decoupled Service


A Layered System for Agility and Reduced Dependencies

Operational Systems/ Data Layer

Service Components (Code)

Service (stand alone application)

Business Process Layer

Consumer Interface Layer (API)


Services are unassociated, loosely coupled units of functionality that are self-contained. Each service implements at least one action, such as submitting an online application for an account, retrieving an online bank statement or modifying an online booking or airline ticket order.

In Other Words

- Wikipedia


Sound Good?


SURPRISE!

- http://www.soa-manifesto.org/

- Open Group (SOA Definition)

- Wikipedia (SOA)


“Many of the problems laid at the door of SOA are actually problems with things like communication protocols (e.g., SOAP), vendor middleware, a lack of guidance about service granularity, or the wrong guidance on picking places to split your system.”

- Building Microservices, Sam Newman

But this approach has Already FAILED…


The Glue Problem


Traditional Service Integration


The Bigger an Architecture Becomes – the More Glue there is


Until it looks something like this…


Integrating an API that is tightly coupled to its underlying service is the equivalent of integrating that service directly.


Something must be glued into your architecture. This is inevitable.


All services will fail.


Traditional Service Integration


However, a representation can be an abstract of the underlying service, substantially reducing coupling.


An Abstraction “Unglues” the Service


Services become Plug and Play


This also means that our biggest risk is not the service itself, but the API that abstracts it.


And designing a flexible, long-lived API is hard.


If APIs were LEGOs


Let’s be honest, we start off with the best intentions


But decisions are made “on the fly,” and things change…


And by the time you hit production…


Is this what you really want to glue into your architecture?


Take a step back to understand and design your API1


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…


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

“

-Dr. Roy Fielding


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…


• 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


Hybrid Approach

Design Development

Continuous, fluid, changeable Static… No turns


The Agile Design Cycle


• 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

Using RAML You Can:


The RAML API Designer


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 Best Practicesaka Don’t reinvent the wheel2


• Use Nouns

• Use CRUD

• Use Hypermedia (HATEOAS)

• Use Accept/ Content-Type

• Return Header Codes

• Return Descriptive Error Messages

Incorporate Best Practices:


Use Nouns.


Use:/users

Not: /createUser /getUser/deleteUser


Utilize CRUD.


Create (POST)

Read (GET)

Update (PUT/ PATCH)

Delete (DELETE)


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


• 418 – I’m a Teapot…• 420 – Enhance Your Calm

Or if you’re feeling super creative…


Use Descriptive Error Messages.


{'exception' {

'code' : 'e3526','message' : 'Missing UserID','description' : 'A UserID is required to edit a user.','link' : 'http://docs.mysite.com/errors/e3526/'

}}

The more information you provide, the easier it will be for developers to integrate your API without contacting Support.


Use HypermediaBut really use it…3


Because REST is STATELESS, we have to have a way to REPRESENT state. That is the purpose of hypermedia, to act as the engine of state for the application.


Hypermedia is a critical part of building a flexible, long-lived API that is capable of representing the underlying architectures in an abstracted manner.


And it’s also relatively easy to implement…


• HAL

• JSON-LD

• JSON API

• Collection+JSON

• Siren

• CPHL

Most Popular Hypertext Link Specs


{"data" : {

"user": {"fname":"first","lname":"last"

}},

"_links" : {”self": {"href" : "/api/user/id/1"

},"messages": {"href" : "/api/message/id/1/lname/last"

}}

}

HAL


Plan for ChangeBecause it’s inevitable4


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


Versioning means rewriting ALL Dependencies


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 Accept/ Content-Type Headers


Have a flexible API Architecture


Test and think through all of your changes


DocumentDon’t be “that developer”5


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.


If you’re utilizing Spec Driven Development and RAML, this should be the easiest part of designing and maintaining your API!


5 minute setup • Always up to date Documentation

http://raml.org/projects


Read My BookShameless Plug 6


Ok – you can find a lot of great resources and presentations readily available online, at sites like mulesoft.com & mikestowe.com


But seriously… it’s free.http://mulesoft.com/restbook


THANK YOU!!!mulesoft.com/restbook


@MuleDevmulesoft.com/restbook

apis for microservices

Technology