My friend Tim Burks (@timburks) over at Google gave a great workshop presentation at the API Specifications Conference (ASC) in Vancouver. His talk was on OpenAPI, GraphQL, and gRPC, but one phase he used to describe OpenAPI definitions you find in the wild caught my attention. He described most of the OpenAPIs out there as “fan fiction”. I think this phrase is perfect for describing what happens in the world of API definitions, and accurately describes the growing number of API definitions you can find littering GitHub and other public locations. Resembling a steady flow of machine readable fan fiction about APIs, with some API producers telling their own story, but for most of the landscape, it is up to the fans to shape the narrative.
You can find professional level OpenAPI fan fictions sites like APIs.guru. As well as hundreds of little pockets of fan fiction littering GitHub, often tagged so they can be found via GitHub topics. You can find my index of API fan fiction on GitHub too. I also have scripts who crawl GitHub looking for API fan fiction, as well as API fiction, and non-fiction. I fancy myself as a curator of the stories being told and retold out there, but also someone who tells stories about the stories I hear. Think of me as the TMZ of the API sector. Ok, at this point, you are probably asking why this is relevant to you. Well, fan fiction is an important expression out of your API community. It is a positive sign that your community is crafting OpenAPI definitions and Postman collections for your API, but it might also be a cry for help, and something you should consider when considering creating your own API definitions, and making sure they are available to your community.
First, fan fiction API definitions show that people care about your API—this is good. Second, it shows that people have a need for machine readable definitions of your API—this is also good. Third, it demonstrates that you should be investing in the creation, maintenance, and sharing of your own API definitions. Since you have such a strong fan-base you might want to consider publishing your API definitions to GitHub, and encouraging your community to lend a hand when it comes to maintaining them. The goal isn’t to silence the voice of your community by creating your own API definitions, the goal is to include them in the process, and encourage them to be part of the story, and help you craft the official narrative. You never know, you might find some fans who are worthy of bringing on in some sort of official capacity to help out with this work.
Fan fiction API definitions play an important role in spreading the word about what you can do with APIs. Even when API providers step up to craft and manage their own API definitions, the versions created by the community may still be relevant. Sometimes the fan version might be more complete or robust than the platforms, and other times it might reflect the needs of a specific stop along the API lifecycle, like generating SDKs, documentation, visualizations, and other solutions. When it comes to Postman collections, these API definitions might go beyond just being a reference implementation, and define a specific business workflow, connecting several different API calls into a single, more meaningful API definition. There are many ways in which a community can express themselves using API definitions, and this is something that every platform should be taking notice of, incentivizing and rewarding whenever possible.
While I wish that all API providers would take control over the narrative around their APIs using OpenAPI and Postman collections, I also realize the value and importance of API fan fiction. I find API definition fan fiction to be extremely valuable in the absence of API providers creating their own API definitions. It also provides me with an important signal regarding the health of an API community—the more passionate fans, the more relevance of an API. Often times that won’t go away even when API providers take control over their own API narrative and actively publish their own API definitions. As part of my API research, I am going to work on a better way to identify and tag authoritative API definition narratives versus fan fiction versions. I also want to continue evolving my approach to API attribution, referencing where I found API definitions, and giving credit to whoever did the hard work to publish each API definitions. Ultimately I want to always be giving author credits to whoever tells the story, be able to differentiate between API non-fiction, fiction, and fan fiction—all of which tell an important story about what is happening within each sector of the API economy.
