This is a republishing of an article that I’ve had around in few places, from the old company blog, to medium, and probably somewhere else. It is good for me to review from time to time the importance and impact of APIs in creating a true customer-centered business. We can probably never say it enough because the “techie” nature of APIs makes them an unusual topic for customer experience and business leaders. But the ultimate users of APIs are humans and the ultimate purpose for them is to facilitate value creation.
Cross-functional collaboration to create APIs
(originally from February 14, 2018)
Recently, a client’s executive team got “choked up” and had their “eyes start sweating” because of such an extremely positive business result made possible by the investments they made in APIs. The APIs in question were first created two years ago to save money and scale their associated business process, which definitely happened. About six months ago, we were able to use those same APIs to facilitate a new user experience for a new set of users. But what made these business leaders so excited, was the speed at which a third-party used these APIs to create yet another transformative process, which also opened up significant opportunity for new revenue.
I’ve always loved the power of APIs (application programming interfaces) — that I could easily make use of the best work of people more experienced and smarter than myself — to make my program faster and better than would otherwise be possible. I’ve also always loved the empowerment of APIs — that with care and love I could create software that would help me solve my needs today while creating the possibility for others (or even myself again) to reuse that software to solve other problems in the future. While I’ve always loved APIs, business doesn’t run on fun alone and its unsatisfying to to create something unnecessary anyway. Fortunately, between the acceptance of open source and the shift to cloud computing, the case for APIs, both using and creating them, is easier to make than ever.
Given that, for this article at least, I’m going to skip the discussion about how to make the business case for investing in an API and focus on how to go about creating an API. This how-to won’t be about the details of designing a RESTful API — there are already many articles about that — but rather, about how to do it sustainably and address two key concerns for the long-term success of any initiative: that the endeavor be fun (rewarding, satisfying, and enjoyable) for the people doing the work and that it deliver real business value.
For my part, in addition to my personal interest in APIs, I’m motivated to share this approach because I’ve seen many teams struggle to develop and maintain APIs well and hope it will be helpful. I’ve accrued some valuable experience by having to use terribly designed APIs (and never wanting to create something like those) and by having created beautifully designed APIs that no one really needed. Ultimately, applying this approach we’ve had both technical success (APIs that 3rd-parties find easy to consume) and business success (savings and earnings coming in through the APIs) and I think you can use it too.
The Philosophy of APIs
As API designers and implementers, and also as business leaders responsible for their creation and delivery of business value, we can’t forget that the ultimate API users are humans. Regardless of how many layers of technology deep the API is or that the API security model is “server-to-server”, when there is a failure of the API, people carry the burden. “Failure of the API” doesn’t only mean technical failure.
Since APIs connect computer program to computer program, it is easy to overlook where and how humans interact with them. Unfortunately, even when the primary consumer of a new API is an interactive UI, it is too easy to design the API without consideration of the user experience it facilitates. Likewise, even when the current user experience is considered, it is too easy to design the API without awareness of the possible near- and mid-term plans of the business. When the primary consumer is another computer program, the likelihood of APIs being designed without concern for humans is even greater. When API design ignores the user and lacks understanding of the user’s goals for adopting the API, it fails to capture the potential business value in its entirety.
As part of leading and facilitating digital transformations, we (at Globant) have become really good at building APIs that don’t fail. We do this by bringing together business leaders, business operators, technical leaders, and user experience designers to collaboratively design APIs so as to maximize their business value. In addition to producing good APIs, everyone involved enjoys the process.
How-to Design Great APIs that Matter
Below is our idealized approach to making APIs. I call it “idealized” because the real world always has special cases. Conceptually, this is how we always strive to approach the process of designing, implementing, maintaining, and evolving APIs. We break it into seven phases — two of which are explicitly meant to be done in parallel, but others may be executed in parallel too. Also, it is important to note that we do not have to know everything needed to finish a step in order to start it.
1: High-level business needs/goals
This is always the starting point. There must be some business reason for doing the work.
This is often communicated informally through a discussion and it is important to create a document capturing our high-level understanding of these needs/goals for further discussion and confirmation.
It is good for this document to include a rough sense of an implementation plan. This should capture the key scenarios and, when already known, explicitly state aspects of the vision that will not be included in the initial release and can be backlogged for future consideration.
2a: API drafting
Understanding the high-level business needs/goals is enough to start work on API design.
This work often requires some research into the technology to be used for supporting the API, which may involve prototyping and/or reading technical documentation.
The key output of this step is an OpenAPI (fka Swagger) spec that is managed in source control, executable by BlueOak Server (although you can use whatever technology you want [ed.: BlueOak Server is still in use on legacy projects, but it is in basic maintenance mode, there are other options, but this approach to executable API is less prevalent than I hoped it would become]), and accessible to the team, the client, and partners, at a URL.
2b: Business requirements
Understanding the high-level business needs/goals is not enough to confidently deliver a system that improves business outcomes. Detailed business requirements, full understanding of the scenarios to be supported, and identification of all the integration points/other system dependencies required to implement those scenarios are needed.
The key outputs of this step are both high-level user stories and identification of the key data necessary in each scenario. The stories should be more detailed than epics, but not necessarily fully fleshed out and ready for the team to estimate and execute. The understanding of the data should be sufficient to drive meaningful discussion and evaluation of the API draft.
3: Synthesis
Neither the API draft nor the business requirements are truly complete until we bring them both together and confirm that the API supports all the target scenarios and that the scenarios are grounded in the realities of a practical API implementation.
Expect accomplishing this synthesis to be time consuming and painstaking. It is most effectively achieved by the champions and stakeholders of the API draft and the business requirements working collaboratively through how each business scenario will be supported by the API.
4: Mock services and mock data
Implementing a mock version of the API is sometimes skipped (“deferred”), and that’s OK. Implementing a mock version of the draft API can be a powerful aid during synthesis too. (There are tools capable of hosting OpenAPI specs and validating requests against them, like BlueOak Server, that generate mock responses automatically.)
The values of a mock version of the API are:
- To allow API users to start implementation against it before the API is fully implemented
- To provide a detailed and tangible point of reference for API developers
- To codify scenarios into data that can be used for all levels of testing
- To provide a fall-back to API users in cases where the real API is unavailable for development or testing
5: Implementation
Having completed the “project-before-the-project” we’re now ready to leverage our traditional Agile processes and implement the API.
The BlueOak Server hosting the OpenAPI spec slowly evolves from only having the API documentation complete, to (potentially) hosting mock versions of the services, to providing a complete implementation against which all the key business scenarios may be executed.
Ultimately, the successful implementation will be promoted to production and will need to be managed and maintained. Given this, it is critical that the implementation include support for logging, monitoring, alerting, debugging, recovery etc. All the considerations of a robust computer system must be part of the implementation in the development/test environments.
6: Maintenance and evolution
Updates to the API, either for defect fixing or enhancements, should, conceptually, follow the above approach too. Worth mentioning explicitly is that any change to the intended behavior needs to be a new major version of the API.
More than a Feeling
This isn’t just a concept and it isn’t just a nice way to work, this is a battle-tested approach to delivering APIs that produce business value now and even more later. It is an approach that enables the actualization of business strategy and can be adopted by any skilled cross-functional team. If you’re just starting to consider how APIs can help your business or looking for some help in accelerating their creation and use, I’d be happy to hear from you.
For that matter, I’d love to hear from you if any part of this approach disagrees with your experience; if you try it and have success (or not); if you want to talk more about the technology used for implementing APIs or how to evaluate a business case for investing in them or the fine art of designing RESTful APIs.
