The API proposal

In a small organization, the API team can usually build APIs independently, but in most larger organizations, an API governance team will approve any APIs being built in the organization. Before you start building an API, you must put together a product specification document that talks about what the API is required to do. This is a simple document that maps out the API workflow and narrates the story of why this API needs to be built.

This API proposal document should map out the workflow of the API, along with various user stories. User stories are written in the format shown in the following figure:

Figure 4.2 – User story format

This format is widely used across all types of products to the goals that need to be achieved by it and communicate the actions that need to be taken in the process.

For example, if you propose that your team builds a shipment tracking API for an e-commerce company, you can start to imagine user...