It’s easy to forget that using APIs depends so heavily on discovery. The average API use case is obfuscated and happens invisibly behind the scenes, so it’s easy to imagine that this process just happens magically.

The reality is that discovery is a huge part of this process. For APIs to function smoothly, they must be discoverable and understandable. A big part of this is ensuring standards for documenting where the most important elements of an API live and how they can be utilized within a broader system.

Below, we’ll examine a tool called APIs.json that enables this functionality. We’ll also consider how the inclusion of its sister project, APIs.io, changes the game. We’ll also consider some general applications, challenges, and considerations around how this tool can be effectively implemented at scale.

What is APIs.json?

APIs.json is a machine-readable specification designed to provide discoverability and operational clarity across a service. APIs.json functions similarly to a sitemap for a website, explaining the operational systems, how they tie together, and where the important machine and human-readable documents exist within the ecosystem of services and systems.

One aspect that makes APIs.json uniquely powerful is that this “sitemap” index is not just concerned with internal services. Internal, partner, and public APIs are collated and documented within the service, allowing for a comprehensive view of the API and its relevant components.

Notably, APIs.json also documents human-readable elements. While documenting the machine-readable pieces is a powerful solution for providing understanding to systems, providing the human-readable element makes it uniquely useful for human end users. This allows for better and more complete integration through understanding.

As an example of this, we can look at Fitbit’s specification:

{
    "name": "Fitbit",
    "description": "Fitbit designs products that track everyday health and fitness, empowering and inspiring people to lead healthier, more active lives.",
    "image": "https://www.fitbit.com/images/common/logo_with_trademark.png",
    "tags": [
        "fitness"
    ],
    "created": "2015-01-01",
    "modified": "2015-01-01",
    "url": "https://www.fitbit.com/apis.json",
    "specificationVersion": "0.14",
    "apis": [
        {
            "name": "Fitbit Web API",
            "description": "Fitbit designs products that track everyday health and fitness, empowering and inspiring people to lead healthier, more active lives.",
            "image": "https://www.fitbit.com/images/common/logo_with_trademark.png",
            "humanURL": "https://dev.fitbit.com/",
            "baseURL": "https://api.fitbit.com/",
            "tags": [],
            "properties": [
                {
                    "type": "X-blog",
                    "url": "http://blog.fitbit.com/"
                },
                {
                    "type": "X-blog-rss-feed",
                    "url": "http://blog.fitbit.com/feed/"
                },
                {
                    "type": "X-github",
                    "url": "https://github.com/fitbit"
                },
                {
                    "type": "X-twitter",
                    "url": "https://twitter.com/fitbit"
                }
            ],
            "contact": [
                {
                    "FN": "Fitbit API Team",
                    "Url": "https://dev.fitbit.com/forum"
                }
            ]
        }
    ],
    "maintainers": [
        {
            "FN": "Fitbit, Inc.",
            "X-twitter": "fitbit"
        }
    ]
}

This is a great example of the additional human-readable context that can be provided. For example, simply mentioning the specific maintainers and the contact information for the API as follows provides a human-readable answer to “who do I contact for an issue to be resolved?” and does so in a way that does not require complexity or expensive landing pages.

"contact": [
                {
                    "FN": "Fitbit API Team",
                    "Url": "https://dev.fitbit.com/forum"
                }
            ]
        }
    ],
    "maintainers": [
        {
            "FN": "Fitbit, Inc.",
            "X-twitter": "fitbit"
        }

What is APIs.io?

Taking this logic one step further, APIs.io, a tool built upon APIs.json, offers even more streamlined discovery. The service is essentially a search engine for APIs. In the same way that Google and other index engines started as glorified sitemap discovery systems, APIs.io has taken this design paradigm to its ultimate result.

APIs.io is not a replacement tool, but it could be an effective way to discover new systems. Notably, it also provides a Browse area to discover already indexed APIs, allowing more seamless discovery and utilization.

The Benefits of Using APIs.json and APIs.io

APIs.json and APIs.io could offer various benefits, such as enabling better communication and making APIs more discoverable. Having additional data could also aid machine readability. Here are a handful of specific benefits APIs.json might enable.

Effective Communication

These tools provide a substantial modality for developers to communicate with their end users. Developers can implement these tools to represent the API design as they envision it, allowing for more clarity in communication. By providing a solid understanding of the inner workings and modalities of the API, connecting users to specific document locations and presumptions, APIs.json and APIs.io unlock a substantial communication modality that otherwise would be obfuscated by the very nature of API user paradigms.

Ease of API Discovery

It’s not just enough to make your API documentation easy to find — even with the best communication, you still need a user to actually be able to find your services. Enabling discovery is a difficult question, but APIs.json, and to a further extent, APIs.io, makes this a relatively easy process.

That ease of implementation is also a huge benefit. What stops most discovery efforts is the friction they create in the development process. Making things discoverable isn’t always easy, and if developers need to go above and beyond for users who may never use their tool, the argument could be made that it’s a waste of time or resources. Instead, tools like APIs.json could provide such a solution with relatively low friction.

Improved API Management

The easiest way to perfect a skill is to teach it to someone else. In the same vein, the best way to ensure that your API is designed effectively is to explain that design to another person. Creating a “sitemap for APIs” forces developers to consider how their systems are designed.

By taking a deep look at their APIs, developers could spot issues around organization, and maintenance can be surfaced. This allows developers to grasp how the system is designed, how it can be made better, and how the end user understands the API from the external point of view.

Facilitation of Machine Readability

Machine-readable systems are easy to integrate and extend, and efforts to that end can pay huge dividends over time. Machine-readable integrations mean a low barrier to further interoperability and unlock major benefits to automation and development.

In essence, machine readability is akin to using a cheat code, helping to de-silo your systems. A huge piece here is that there has been a massive investment in machine-readable API specifications with low friction for implementation. With options such as OpenAPI, AsyncAPI, and JSON Schema, machine-readable systems have never been easier to implement with more potential upside. In other words, the cost of not implementing machine-readable solutions is far greater than the cost of implementing them.

Community and Ecosystem Building

API users are easy to view as a monolith, but the reality is that every user has their own considerations, concerns, and use cases. These users need a network of support to effectively use your systems, and providing something like APIs.json and APIs.io as a discovery engine can enable community development around your APIs.

This has huge impacts on long-term API utilization and retention but also has tack-on benefits for open-source collaboration. When systems connect with one another and allow users to coalesce around use cases, these systems unlock huge benefits at scale.

Challenges and Considerations

Some concerns could be raised around APIs.json and APIs.io. Firstly, there are obvious concerns about security and privacy. When sharing intricate API details, developers should consider what elements of their API need to be surfaced, and which do not. That said, adopting the proper zero-trust API security should make the surfacing of machine-readable API descriptions trivial.

Developers may also be concerned about additional processes. Using these tools does require time and resource investment, and some developers — especially those who only provide single APIs — may view using these tools as just another cost with low benefit.

While single-API developers who don’t lean on other systems may be accurate in this assessment, the level at which developers begin to benefit from APIs.json and APIs.io is actually pretty low. If you, for any reason, need to surface your systems and make them discoverable, these tools are great ways to do that. For this reason, this problem is relatively self-selecting — if you view this use case as too costly, it likely will be.

Conclusion

APIs.json and APIs.io are wonderful tools that can help deliver substantial benefits to most organizations. Through some basic design considerations and proactive development, they can offer huge benefits in community development, automation enablement, and new discoverability.

What do you think of this tool? Are there other discoverability tools you’d like us to look at? Let us know in the comments below!