1. Who Needs Your API? Flashcards
What are the five steps to take prior to building a RESTful API?
- Decide what functionality to expose
- Decide how you want to expose it
- Decide the best ways to expose it
- Test and (in)validate assumptions
- Repeat
What are the challenges to a good API design?
Naming things well while simultaneously describing how to interact with those things. Also, as the API sees the real world, the goals and the purpose of the API will evolve. This may require us to find better words to describe our efforts and adjust accordingly, which gets a versioning and backwards compatibility.
What are affordances in the context of APIs?
Something that allows you to perform an action or accomplish a goal. Everything that you allow a user to do is an affordance.
eg. A door knob is an affordance that allows you to open a door.
What are the three different “what”s that are in play when it comes to affordances, and what happens if they aren’t aligned vs are aligned?
- What the API does
- What the API makes easy
- What the user wants to do
- When these aren’t aligned, we may have a useless API, or maybe a powerful API that doesn’t do what we need.
- When they are aligned, we have a unique combination that’s incredibly powerful but so subtle you don’t even notice.
What are the two approaches for adding an API to your system?
- The Bolt-On Strategy
2. The Greenfield Strategy
What is the Bolt-On Strategy?
An approach for adding a new API to your system. It’s used when you have an existing application and add an application “after the fact”.
What are the two benefits of the bolt-on strategy?
- Brute-force approach but is generally the fastest way to get something useful since the underlying system is functional the whole time
- Takes advantage of the existing code and systems so you don’t have to re-think anything.
What is the drawback of the bolt-on strategy?
- Problems in the application and architecture tend to “leak through” into the API.
What is the greenfield strategy?
An approach for creating a new API when there’s no underlying application, or even necessarily business logic, that you have to interact with — you have complete freedom and flexibility to do whatever you want, however you want to do it.
What are the two benefits of the greenfield strategy?
- The easiest scenario to develop an API in.
2. Takes advantage of new technologies and architectures, and possible reinvigorates them
What is the drawback of the greenfield strategy?
- Often requires massive upfront investment before any benefits are gained
What is the facade strategy?
An approach for creating a new API where you take advantage of the existing business systems, yet shape them to what you prefer and need. It’s somewhere in between the bolt-on and the greenfield strategies.
What is the benefit of the facade strategy?
It gives the ability to keep working systems in place while making the underlying architecture better.
What are the two drawbacks of the facade strategy?
- It can be challenging to have “multiple mindsets” in the system.
- It can be hard to replicate behaviour for full 1:1 conversion.
What are the three simple rules for modelling APIs?
- Don’t worry about tools. (NoteCards, Post-it Notes, Kanban, etc.)
- Have a consistent process.
- It doesn’t count unless it’s written down (document everything!)