February 14, 2018
Recently, we had one of our client’s executive team get “choked up” and have their “eyes start sweating” because of such an extremely positive business result made possible by the investments they’ve made with us in APIs. The APIs in question were originally created two years ago on an integration platform they trusted us to build a year previous to that. At the time, their purpose was to save money and scale their associated business process, which they definitely did. 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 a transformative process for a critical piece of their business, which also opens up significant opportunity for new revenue.
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 seems to be or if the API security model is for “server-to-server” communication, when there is a failure of the API, people carry the burden. And “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’ve 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, our teams and clients enjoy the process.
Below is our idealized approach to making APIs. We 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, 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.
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.
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
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 just a concept, this is a battle-tested approach to delivering APIs that deliver 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, we’re ready to help you, from strategy through to maintenance and iterative enhancements. Just let us know.