Restful API Design - User Stories to Design Spec
Rest is an architectural style and that leaves lots of discussion and debate on the standards of details from design to implementation. Here we will discuss how a Restful API could be designed from requirements and considering various debates that exists in the industry and developer community.
Restful API Home page covers many fundamental concepts. It is suggested that you have those understanding before attempting design. A good API makes is easy to develop a program by providing all the building blocks intuitively and efficienty.
It all starts with business requirements. However, APIs are technical components and it needs a creative approach starting from requirement gathering. What is the business case that API solves?
In a case study done by McKinsey they explore how a platform transition is possible. APIs in an organization could be segregated in to three levels.
Customer Journey API
Business as Service API
IT APIs
It makes sense to take a look at API from these three perspective. APIs will be used by developers to integrate or build yet another system. However, the ultimate purpose is to solve the issues users of the final product faces. Looking at API from the perspective will give a complete picture of the API and user persona it will deal with. Thus first part of our journey is to identify user persona.
Identify User Persona
Users of APIs are much more than developers. There are 'user' persona and 'system' persona. When the stake holder is a real person it is a user persona and when it is another system it is a system persona.
Identifying personas require subject matter expertise, business analysis experience and creativity. When it comes to APIs the business analyst of the product owner should have a decent technical background as well.
If it is a banking API who all you think could be potential user personas?
System Integrators who connect services together,
Partner Enablers who develop solutions for partners
developers ranging from internal IT organizations to developers of public APIs,
Testers of API
all these could be user personas. Looking to the API from each of their perspective will help the product owner com up with a complete set of user stories.
Develop User Stories
A sample user story in te banking scenario mentioned case could be:
"As a Banking Customer I want to fetch the account details so that I can see my account balance".
Add details to the user stories, as a product owner will usually do. Include acceptance criteria and any other details that will make it a good story.
Identify Models
Rest APIs are based on the concept of resources. This has very close similarity to the Object Orientation in the OOPS concept. This makes it easy to visualize associations, aggregation and composition. A similar thought process is helpful in identifying RestAPI Models.
Models will eventually map to the resources via rest API URI. If User stories are written, a designer could look in to those and extract models easily.
In the user story mentioned above Account, Customer etc. are natural models. Once the models are identified, detail it with its attributes. If a Customer model contains Account Model, include that as well. A good example could be drawn from swagger sample models.
Given below is a sample from swagger
Map User Stories to API
Once the models are identified and filled with attributes, identifying APIs along with its input and response becomes very easy. Any capability the resource requires could be potentially an API that needs to be exposed to the outside world.
Document API URI
As we progress through the Rest API Design, we need to document Rest API URI. This is an important part of the exercise as it will be exposed to the outside world. You need to have Rest URL and Resources name standardization.
Noun and Verb Debate
Rest APIs are based on resources and it is natural to think that a resource will be identified as noun. A verb will be an action and thus not a resource. This has triggered numerous debate in the developer community. And as always, there is no conclusion to it.
My recommendation is, it is perfectly okay to use nouns are part of an URI when it is absolutely necessary. There are standard APIs such as Github APIs takes this approach selectively, such as in star a repository. and And moreover, it is most important make the APIs inituitive and usable than picking on minor details. Practically, there are ways to revert to noun option, even when an action is required. For example. 'activate' could be converted to activations and treat it as a resource.
If you are choosing a noun for some reason, get it peer reviewed and take suggestions. Idea is to stay with nouns as long as possible.
Develop Open API Specification
Once you have done the steps above, converting to a OAS spec should not be hard.
You have User Story, Resource details, URI and it naturally flow to a swagger document. OAS YAML itself is not that hard to understand, it is recommended that you go through the basic structure and understand the same. The consult some sample OAS YAML spec to create your own.
Conclusion
There are multiple approaches and debates when it comes to Rest API standards. But you should have a process to traverse your API project from requirement to design. Design itself is not pure science as it involves creative elements also. The right skills will come through experience. The process detailed here will help you convert your requirements to a design spec.