I spend a lot of time gathering, creating, and organizing machine readable OpenAPI Specs, as part of my API Stack, and personal API stack work. I'm not insane enough to think I can create OpenAPI Specs for all of the public APIs out there, I'm just trying to tip the scales regarding how many API definitions that are out there, to increase the usage and value of open tooling, which in turn will increase the number of people who will create their own OpenAPI Specs. (just kind of sort of insane)
As I do this work, I realize how easily I can obsess over unnecessary, and meaningless metrics and goals in the tech space. Two things have stood out for me as I do this work:
- Overall Number of API Specs - Much like our obsession over the completely meaningless and incorrect number of APIs that are in the ProgrammableWeb directory, the number of OpenAPI Specs means nothing. At some arbitrary point, things will change and people will get on board--it is already happening.
- The Complete OpenAPI Spec - Having a complete OpenAPI Spec that contains ALL endpoints, parameters, and underlying data schema is a myth, and really doesn't matter. You only need as much as you are going to use. Maybe to API providers this matters, but to consumers, you only need what you need. The trick is figuring out what this is, without dumping everything on a consumer.
I won't stop what I am doing. As an experienced technologists I know when I am simply a tool in a larger game, and I perform as the automatron that is expected of me. However I will not obsess over the completeness of the API specs, or ever showcase the overall number of OpenAPI Specs that I have--I'll just keep on working.
In this data driven world, it is easy to get caught up in focusing on mythical, meaningless, data points. I'm not saying we shouldn't be doing this, because I often use these data points to motivate and push my work forward, but I think the lesson for me, is to know when an obsession over some arbitrary number becomes unnecessary or unhealthy. Another important aspect of this realization for me, is separating out when I personally set these number, or they are handed down from the wider tech space, and I had no part in helping craft them--this is when I think the chance for moving into the unhealthy realm exists the most.
