Why you should start your solution by designing a great API

1. SIXTREE 2015
API & Microservices Meetup#1
Welcome
Background
Goals
Rules
Next event: Venue & Speakers

2. SIXTREE 2015
API-led DesignDamian Harvey, Principal Consultant
Sixtree.
Auckland API & Microservices Meetup#1

3. SIXTREE 2015
Why? Avoid fail. Move fast.

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

5. SIXTREE 2015
API rock-stars

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

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

8. SIXTREE 2015
We all like good design

9. SIXTREE 2015
Good design:
1. Is innovative
2. Makes a product useful
3. Is aesthetic
4. Makes a product
understandable
5. Is unobtrusive
1. Is honest
2. Is long-lasting
3. Is thorough down to the last
detail
4. Is environmentally friendly(?)
5. Is as little design as possible
10 Commandments of good design
- Dieter Rams. Design legend.

10. 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?

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

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

13. 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 API
o 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

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

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

16. SIXTREE 2015
APIdays 2015: Auckland October 19