SIXTREE 2015

API & Microservices Meetup#1Welcome

BackgroundGoalsRulesNext event: Venue & Speakers

SIXTREE 2015

API-led DesignDamian Harvey, Principal ConsultantSixtree.

Auckland API & Microservices Meetup#1

SIXTREE 2015

Why? Avoid fail. Move fast.

SIXTREE 2015

What are APIs?• When we talk about APIs we are talking about “Web” APIs.• Bits of logic that encapsulate the data they operate on and provide an

interface as the only way to access their functionality.

API-led design means:1. Starting the solution design process with APIs and 2. Crafting APIs rather than throwing them up.

Back up a bit

SIXTREE 2015

API rock-stars

SIXTREE 2015

• Increase Agility• Consume rather than build.• New business models• Self-service IT• Composable Enterprise• Mobile enablement• Parallel development• Governance & Control

Why APIs?

SIXTREE 2015

What is Design?• ‘Making things better for people' - Richard Seymour, Design Council 2002

• Design is a work process which has a user perspective and drives development based on your specific customers’ needs

Who is the API Customer?Developers? The Business? Both?

Back up a bit more

SIXTREE 2015

We all like good design

SIXTREE 2015

Good design:1. Is innovative2. Makes a product useful3. Is aesthetic4. Makes a product

understandable5. Is unobtrusive

6. Is honest7. Is long-lasting8. Is thorough down to the last

detail9. Is environmentally friendly(?)10. Is as little design as possible

10 Commandments of good design

- Dieter Rams. Design legend.

SIXTREE 2015

• Alignment between Business, Stakeholders & IT• APIs are crafted in response to a customer need rather than generated

from a developers code (hide your complexity).• Quicker and cheaper to make change during design phase.• Once it’s code it takes longer (even if you have great DevOps)• Allows engagement with Customers in the creation of the API. • Prototyping.• Enables parallel development of front-end and back-end.• Self-documenting.

Why lead with API Design?

SIXTREE 2015

What’s the alternative?• Typically code your web services and pull them up into an API

specification.• Focus is on the service developer not on the API consumer.• Result is an API that shows all of the complexity in your

codebase and domain.• Result is nasty APIs. Poor engagement. Fail.

SIXTREE 2015

5 steps:1. Create high-level domain model (get the language right).2. Model the state (get the actions right).3. Create the API outline in an API specification language.4. Verify that the specification conforms to domain. Update if needed.5. Flesh out the specification with low-level “developer” detail.

API Design methodology

SIXTREE 2015

• Avoid dumping the whole Domain into the API.• Avoid “Fat” APIs that cover too many Domains

o eg. /flights, /employees, /invoices all in the one APIo Fat APIs change too frequently. Favour multiple smaller APIs with fewer

owners.• Avoid inconsistent naming

o eg. resourcename not resourceName, resource-name, resource_name.o eg. passenger, pax, customer, cust – pick one. “Ubiquitous language”

API Design anti-patterns

13

SIXTREE 2015

RAML• RAML stands for RESTful API Modeling Language.• Based on YAML, so if you like tabs….• Open specification created by MuleSoft• Alternatives: Swagger, API Blueprint, WADL(?)…etc• Mule Anypoint API Designer (free) has great RAML editor.• Can mock out API once specified.• Can generate code (eg. JAX-RS, Go) from RAML.• Generates excellent documentation with live interaction.

SIXTREE 2015

Conclusion• API-led design isn’t about adding roadblocks.• It’s about crafting something that will have value.

SIXTREE 2015

APIdays 2015: Auckland October 19