Application programming interfaces are invisible to most people including most software developers. Folks using mobile applications or web applications are oblivious to the fact that much of it relies on your API and without having access to the code base or being able to read the code for most people your API will remain unseen. However this does not make it permissible for the API to remain unseen or an acceptable practice to continue doing so.
In order to visualize the API and to bring it to the forefront we make use of industry standard flowcharts to document the internal processes of the API. As a high level diagram we will document only the essential process flow of the API but as this series progresses we will refine the diagrams to include actual procedure and function names.
In the diagram above I have drawn the basic swim lanes for both the GET and POST methods we will be designing. For the GET method we will be extracting a variable from the URL path and return it to the caller as a formatted JSON response. For the POST method we will extract the same variable from the body of the post after having validated the data for accuracy.
Flow charts such as these are a necessity in order to visually describe an API to other technical and non-technical persons and should be an inclusion in any API’s documentation. As a solutions architect of many years I generally employ a rule-of-thumb to separate each major stage, process or system in to its own swim lane for clarity. I also use colors quite a bit as it is human nature to identify with and respond to color. In the course of the series I will demonstrate how to give rise to clean and articulate API documentation.
Up Next: Describing The API