What Is An API?
A common software development requirement for Agile teams is to develop an application programming interface (API) so that a particular software system can be accessed in a structured way. However, a lack of clarity around the purpose of the API can lead to a mismatch between the team’s efforts and the ultimate requirements for the system.
If you ask a developer what an API and its documentation are, you are likely to get one of the following responses:
- An API is the interface to the code I wrote. The documentation describes how it works.
- An API is the interface between an established system (that we can’t change) and a new system that we are writing. The documentation describes the activity of the external system and we use that to adjust our code so that the two can talk.
- An API is a contract between two systems to enable them to talk together. The documentation describes how each should function in order to interoperate effectively. The API is not the code, it’s the agreement.
So, which is it?
Three Wise Women and an Elephant
Which answer you get often depends upon which wise woman you ask.
The Programmer
If you ask a programmer what an API is, you will most likely get answer #1. This is because in today’s software development environment there is a lot emphasis on creating new services and microservices. Also, Agile processes tend to favor quick spurts of development and eschew contracts and documentation. This is a programmer-driven approach. There are a number of tools that a developer can use to automatically generate API documentation from code. You may find your developers using these tools because they would rather do anything than write documentation.
The Archeologist
Answer #2 most often arises in defense and large enterprise applications where you are charged with interfacing to an existing system that can’t be changed. In this case you aren’t building an API at all, but rather interfacing with an existing one. However, you may still be called upon to document it for your own use, especially if there is no or poor extant documentation, such as in the case of reverse-engineering a solution.
The Business Person
A business-centric view of an API is represented by answer #3. In this model, the Agile team is developing a set of functionalities that customers can use. The developers make the API, but the customers have a strong interest in making sure the API is convenient to use, fits their use cases, and does not change in a chaotic fashion. Indeed, without the customers, there would be no need for the Agile team or the service itself.
The Scrum Master’s Role
Of course, there is no best approach, only more or less appropriate choices based on the problem at hand. The Scrum Master can bring value to the Agile team by helping to determine the best approach from the project outset. For example, if the API is to a set of microservices that are only going to be used internally, it might be that approach #1 is best. Conversely, if you are developing a customer-facing API, then approach #3 is clearly the best choice.
The Scrum Master can and should advocate for a clear architectural approach at the beginning of the project. See “Getting Architecture Right in Small Scrum Environments” for a discussion of this issue. As a part of this architectural effort, the Scrum Master can probe senior management and product owners for a clear view of the business goals of the API. Once this is established, the Scrum Master can communicate it to the team. This will help in calibrating API documentation activities.
Another determining factor is whether or not a test-driven development approach will be used for the project. This will also be determined in the early architectural phases. In a test-driven environment where approach #3 is clearly specified before code is written, tests can be developed in parallel, or even before, the primary service code is developed. In fact, the presence of test code can be an aid to the primary developers to ensure that their own code is working as expected. In this scenario, responsibility for documentation can be moved away from the primary developers, something they may appreciate and a potential carrot to get them to move away from approach #1.
Identifying the approach to API documentation is central to the Scrum Master’s role, because it is about developing a shared vision and goal within the organization and communicating and advocating for that within the Scrum team.