So many of the things that I need to do right now involve taking API design and slicing it into small pieces that can be easily communicated and acted upon. We are working to update our Microsoft Graph API design guidelines and publish them. We are working implementing our SDK generator (Kiota) and we need samples for testing. In the OpenAPI Initiative, we are always looking for more examples of how to use OpenAPI to describe APIs. But where do you start. There is so much to cover and breaking it down into pieces seems like a good first step.
As an example of this breakdown, I identified that all path segments tend to falling into one of the following types: category, data partition, version, global key/value pair, collections, items, relationship, mult-segment, matrix, view, action, function.
I started the process of documenting what each of these mean, and giving examples, and as I explored the areas of query parameters, requests, responses, and interactions, I realized that this blog post was going to turn into a book and I would never be finished.
In spirit of breaking things down, I created a GitHub repo where I will continue to provide details. Along with each defined term, I plan on creating an OpenAPI description of an API that demonstrates the term. The intent is to provide people building tooling an exhaustive set of scenarios that developers can use to test their tools against.