Modeling Our Onboarding API Cycle
Learn how to model our Onboarding API cycle.
We'll cover the following...
The process of modeling an API involves collecting all the information we need in order to properly describe the tasks we want to accomplish, the data needed to get that work done, and the process or workflow needed to support all the tasks. For the most part, this is common-sense data collection and description, but it’s important to put together a kind of method or repeatable set of steps that we can use each time we want to model a new API.
It’s likely that we’ll be asked to help a team turn a manual process into an automated one using an API. Sometimes APIs or applications already exist. They do one or more parts of the expected work, but don’t work well together. Sometimes just a few parts are missing. Quite often, a company has a fully functioning API, but the workflow or data requirements have changed, and it’s our job to go in and help update an existing API to meet the company’s new needs.
Regardless of the reasons, the real work of modeling the API starts with asking lots of questions and collecting lots of information. Then we need to turn that information into some type of document that everyone can understand, review, and approve before we get too far into the actual process of building the API.
An easy way to do this is to use a simple pattern of discovery that involves two key steps we can repeat again and again until we’ve gathered enough information to work on the API directly:
-
Map out the API workflow and identify the internal cycles: The API workflow document helps us see the big picture of what we’re working on. The internal cycles document helps us focus on the details of each small step in the overall workflow.
-
Write an API story document: The API story document is just that—a narrative document that explains just what the API is meant to do, along with the data properties and actions that “animate” that story.
Step 1 is focused on gathering and organizing all the ...