We have been slowly rolling out the Streamdata.io API Gallery over the last couple of months, and we are working to continue to refine the APIs we have already profiled, adding more details about the APIs and their operations. We are also looking to add new API providers to the gallery, and are happy to accept new submissions, but to be able to help us prioritize your API, we wanted to share some technical details with you regarding how you can streamline the process and add your API to our machine-readable API gallery that runs on GitHub.
The entire Streamdata.io Gallery is driven using machine-readable definitions, including APIs.json, OpenAPI, Postman, and AsyncAPI collections–all stored within a Github base. Each individual entity or API provider profiled as part of the Streamdata.io API Gallery operates as a standalone GitHub repository, within a GitHub organization filled with API definitions. This approach allows us to scale the entire API gallery independently in a way that allows each repository to be forked, downloaded, as well as allowing API providers to profile their own APIs. Which helps us expedite the API profiling process, and quickly onboard new APIs as part of the distributed API discovery engine.
If you’d like your API added to the gallery you can take a crack at profiling your API for us, and submit with the following elements in action:
– Github Repository – Create a basic repository, with title, and description of your API as the README in the root of the repo.
– APIs.json – Add an APIs.json index of your API operations, describing what it does, and provide links to the various elements of your API platform like signup, documentation, code samples & SDKs, plans & pricing, terms of service, and other building blocks.
– OpenAPI – Providing an OpenAPI definition that defines as much of the surface area of an API as possible, describing paths, parameters, responses, schema, and other technical details needed for integrating with an API.
– Postman Collection – Importing an OpenAPI into Postman and exporting a machine-readable Postman Collection with or without the environment included in there.
Not all of this is required to submit your API to us, but the minimum needed for inclusion in the Streamdata.io API Gallery is a GitHub repository, APIs.json, and an OpenAPI definition. How complete these definitions will ultimately be is more art than science. Ideally, we want as much of the API operations, as well as many of the API paths defined for inclusion. We are happy to do as much of this work as necessary, but the challenge is always carving out enough time to actually get it done, which is why we ask API providers to bring as much detail to the table as possible, to eliminate as much friction as possible.
Some companies just share the link to their OpenAPI with us, leaving us to create the Github, APIs.json, and Postman Collections. We encourage you to maintain all the definitions we require within your own repository. It is something that leading API providers like Slack, Box, and New York Times do, and represents a health practice. If you follow this practice we can then fork the repository for inclusion in the API gallery, leaving you to manage your repo and evolve your own API definitions. Making sure you possess and are evolving your own API definitions is critical to the scalability of your API operations–we are just interested in getting our hands on your API definitions so we can help ensure you will get more exposure and distribution for your API as possible.
