It's useful to think about an API as 3 things that can (and should be) decoupled.
The definition of the interface, the documentation, and the code of the interface itself
→ For the interface we want to optimise the client experience.
The code that implement the work the API is suppose to do.
In our case image processing, manipulation and storing.
The way the image processing is done, and the logic behind can be different than the interface.
→ Implementation wants to be efficient
From the code of the interface and from the code of the implementation, we can run an instance
→ an instance wants to be up and running all the time, fast, and need to be monitored.
Need to answer 2 questions:
- Why do you want to build an API?
- Monetise internal assets?
- Harvest business data?
- Increase business aligned capabilities in your platform?
- How the API will help you reach that goal?
- How the strategic impact measured?
- When the strategy change?
- Vocabularies
- Styles
- Interactions
- Safety
- Consistency
→ openAPI spec can help
2 Styles
- Tell don't teach
- When it's explained in details what the API does
- Teach don't tell
- When there are just examples
When write the doc?
- early and often
- If needed to check if there are some design issues
- at the end
- If priority is to save time and write a coherent piece.
→ using API description close to the code is a way to keep the doc in sync
Quality == testing
Need decisions about what to test and how to test
How much testing is enough?
What can be tested?
- Usability
- check if users have trouble using it
- Unit testing
- Identify bugs in the implementation code at a granular level
- Integration testing
- Identify bugs by making API calls against an instance
- Performance and load testing
- Identify non-functional bugs in a deployed API instance
- Security testing
- Identify security vulnerabilities in the interface, implementation and instance
- Production testing
- Identify usability, functionality and performance bugs in the production environment
- Dealing with uncertainty
- A popular method for eliminating uncertainty is the principle of immutability
- immutable deployment package
- immutable env variable
- The more is not allowed to change the safest
- Deployment automation
- doing work more quickly vs doing less work
- Deployment tooling and automation can be a quick win, but can limit flexibility and have a maintenance cost
- Deployment gouvernance
- Who decides when a release happen
- How the decision is communicated?
- What is security?
- Protecting your system, your API client and the end users
- Keeping the API up and running for legitimate use by legitimate users
- Protecting the privacy of data and resources
- Security is part of all the pillars
- How much security does an API need?
- What to monitor
- Problems (errors, failures, warnings, crashes)
- System health (CPU, memory, I/O, container health)
- API health (uptime, API state, total messages processed)
- Messages logs
- Usage data
- Gouvernance:
- What should be monitored?
- How is data collected, analysed and communicated?
- runtime discovery
- to list instances automatically
- design-time discovery
- Marketing
- When and how the API is advertised?
- Choosing the best changes to make
- Implementing thoses changes as fast as possible
- Making those changes without breaking anything
Gouvernance: Witch change need to be fast and witch change need to be safe?
Goal is to move fast while maintaining the quality.
- interface
- implementation
- instance
- Plan
- do
- the code change, the deploy
- study
- Act
- comunicate
- update goals?
- Tooling and automation
- Tools exist on the market for all part of automation
- better to test carefully on an experimental basis
- up front cost and risk with new tooling
- Organisational design and culture
- what is the coordination needed to make a change?
- Eliminating wasted effort
- for instance an internal API don't need a perfect documentation
- Effort cost
- tools, organisation, beyond the scope of this book
- Opportunity cost
- Lean startup methodogy for nothing critical
- gather as much information before making a change
- Coupling cost
- Biggest problem is the coupling between the API and what consume the API
- The BDUF (Big Design Up Front) witch is an anti patern from the Agile manifesto is difficult to avoid for API.
- API tend to be difficult to change once they are made and published
