API’s as a product
Companies ignore API’s till it is too late. I have seen this happen repeatedly and then it is a significant amount of rework to get API’s right.
There is, IMO, a very clear way of doing things right.
Most companies start out being product companies. This means the focus is on a great customer experience, a good product-market fit. Everything else is secondary, including API’s. The compromise made in solving for customer experience are haphazardly developed API’s with no consistency and no strategic thoughts in build API’s.
At some point in the future, a customer, possibly larger, will come around and say ‘Hey, can I integrate with your API’s instead? I need to perform operations in bulk’. And you look at your API’s and think that if they ever saw what a can of worms it is, they would stop using you (not to mention all the security gotchas that you swept under the rug). So the solution? You create a new set of API’s meant for external consumption. And now you have two problems. Much like what Jamie Zawinski said:
Some people, when confronted with a problem, think “I know, I’ll use regular expressions.” Now they have two problems.
So now you have two ways to access potentially the same, or overlapping, functionality. So changes need to be duplicated in many cases. Performance needs to be checked for multiple routes.
Instead, I believe development should be API first. I like following this methodology:
- Define the mechanics of the API. Do you support REST? GraphQL ? Possibly even both ?
- Define the implementation semantics. At Inflection, this document guided RESTful implementations -https://blog.inflection.com/api-guidelines/
- Define the landscape of the API’s. What are the domains? What are the common attributes and objects? Keep this set as small as possible. I find Domain Driven Design/Event Storming to be a difficult but rewarding exercise to discover these.
- Finally, identify your API team. Have a small team who understands the big picture of the domain landscape and are API experts. This team helps ensure consistency with the Domain Design, design principles and act as resources to help teams. All API endpoints must be reviewed by the this team. (You have to scale up or scale down this process based on the maturity and size of your team). Have a strong API czar who understands both the tech and the business strategy to ensure the API’s reflect both.
Once this baseline work is done, the real work begins.
- The user stories are written.
- The Product Manager and engineer agree on the shape of the API to support the user stories. In some cases, these are new domains and completely new API’s. In other cases, they might require versioning of existing API’s (which is covered in the RESTful implementation guideline). These are decisions that the API czar helps make.
Once the API’s are defined, the front end team is off and running — mock servers can easily support the new API’s right away. The micro-services teams can build the biz logic and persistence required to support the new APIs. Both the back end and the front end — indeed, even the customer integration — can proceed in parallel. This ability to run in parallel based on API definitions injects confidence and velocity in the team
Build world class documentation
A plethora of tooling makes it easy to build great documentation. But engineers do not like writing documentation. See the code, they will tell you. But great documentation is really important. Great documentation will save you lots of time answering questions from other internal teams. It allows meeting-less collaboration. External consumption of API’s is easy.
Build Strong Governance
This is worth harping on. Excess process is always a bad thing, but the right level of process is gold. In case of API’s, the API team’s review is essential. Versioning must play by the rules, or it will cause pain to all users of the API. And which API’s to open to customers should be a simple flick of the switch.
The API is the platform
Forcing designs that are API centric helps build platform centric teams. This is good in many ways. Teams collaborate with each other with no meetings. Engineers do not care how the API does what it does. All they know is if they call the endpoint with proper semantics and data, they will get the response they need. From their perspective, the API is the platform.
Successful companies will, over time, morph into platform companies. You can help plan for it by paying due heed to the quality of the API’s you build.
