The goal of the first phase is to analyze the “problem domain”, identify resources and sketch a simple API description for each resource. This API description can be verified by simulation and integration into a demo app.
The first step of a domain analysis phase is gaining some clarity on the needs of the consumer and possible usage scenarios. Sketching usage scenarios is a creative act. It is a good idea to involve multiple and diverse stakeholders in this initial brainstorming phase.
Start by asking yourself:
• Who are the consumers of the API?
• What is the purpose of the API?
• Which API solutions do the consumers plan to build with the API?
• Which other API solutions would be possible with the API?
Even though the development of new APIs is usually triggered by a concrete project, the goal should be the development of a generic API. Thus, not only the usage scenario at hand, or the obvious usage scenario should be sketched. Ideally, a broad set of usage scenarios for the API should be sketched. Sketching can be either in some form of graphics or in the form of text.
The next step is to build a resource taxonomy for the given usage scenarios. Think from a consumer’s perspective about the usage scenario, try not to have the tinted view of some existing backend structure or existing database tables, since those provide an internal view. Take on the view of the API consumer. How would an API look like that she wants to use? What apps would the consumer want to build? What data objects would the consumer want to use in her apps?
To create a taxonomy, write down the usage scenario, then select the nouns in the text. Shortlist the nouns that would make sense as resources, i.e. nouns that describe data objects, which the operations create, read, update or delete can be performed on. As part of the taxonomy creation, one needs to analyze the relationships between the resources:
A dependent resource cannot exist without the other. An independent resource on the other hand can exist without any other resource. Associative resources exist independently but still have some kind of relation, e.g. they may be connected by reference. The next step is to think about the states of the resources and possible transitions between the resource states.
The resources in the taxonomy have states and during the execution of the app, the resources may change their states and transition into new states. Express the states and transitions in a state diagram.
Which insights can we gather from the state diagram? The states provide an indicator for the resources that are needed. The transitions in the diagram provide an indicator for the HTTP methods that need to be supported.
With the information collected during domain analysis, a first API description can be built with an API description language (see chapter [chap:API-Description-Languages]). Admittedly, this first iteration of an API description is rather a sketch than an architecture, but it still allows defining the taxonomy, the API resources and their operations.
Verification: Simulation & Demo App
A good simulation allows us to answer some questions about a planned system without having to spend all the effort of building that system. At this stage, the simulation can help to define the purpose of the API: Does it make sense to build an API with the given functionality for the usage scenarios at hand? Does the sketched API help me build the solution? Are the requirements of the API properly captured in the API description?
To answer these questions, a first, low-fidelity API prototypeAPI Prototype should be built. Such an early prototype should only be built, when the effort for creating the prototype is minimal. This is why the API prototype should not be implemented manually, but it should be constructed automatically by generating a simulation based on the API description. Frameworks for API description languages offer such capabilities for generating simulations.
The simulation provides a verification of the stand-alone API. Even more effective would be a verification of the API in the context of an app or solution. This is not necessarily an app with real requirements. A simple Demo Appdemo app for an artificial problem is sufficient for this phase. The simplest demo app would be a little bit more than a curl call. The demo app provides a showcase for the API and can be reused in later stages.