IETF API Catalog vs APIs.json

[UPDATED (06–05–2024) with Apis.json creator response (see below)]

[UPDATED (06–17–2024) with Apis.json creator response (see below)] Mr Lane has now gone back to evangelizing on his own platforms BUT admits that he should be using ‘api-catalog’ rather than trying to invent his own thing

API’s can be difficult to find if they are not documented well. API discovery is about making api’s easier to find for clients/developers so that they can be accessed and developed for.

Currently there is one ACTIVE spec and one competing spec:

• api-catalog : a currently active and under review spec by the IETF(Internet Engineering Task Force) allowing spidering of your apis by agents/search engines.
• apis.json: a non-standard json format created in 2014 with no industry adoption and rejected as a standard. This project by api evangelist Kin Lane, currently requires everyone in the world to submit a schema to his personal database

We will go over these two specs and examine them side-by-side to see how they compare to each other.

The Industry Standard : api-catalog

In order to host an api-catalog so it is discoverable, you need to put it under the following directory on your site (or route to it with the following URL):

• https://YOUR.DOMAIN/.well-known/api-catalog

NOTE : You must always use ‘’well-known/api-catalog’ as the path as this is part of the spec.

Then at that location you use the linkset schema(see below)and requests are made using:

GET .well-know/api-catalog HTTP/1.1
   Host: yoursite.com
   Accept: application/linkset+json

The linkset document looks like the following (due to constrainst, we are showing only ONE ENDPOINT):

PROS

• The BIG PLUS to this schema is that it has industry backing and is being supported by an industry body… not just one individual.
• Schema is a standard
• Promotes discovery by agents/search engines

Non standard : apis.json

In 2014, api evangelist Kin Lane promoted his own schema called APIS.json for ‘api disovery; this never had a backend implementation or agents for spidering and thus never went anywhere.

… its penetration in the API economy is relatively limited, considering these capabilities and how long the standard has existed — Chris Wood, Principal Architect at Ozone API

Recently however, he has been trying again to push his non-standard solution by creating a searchable database with an api; it merely requires EVERYONE IN THE WORLD to submit a schema of their apis to his database!

PLUS… the people working on it, don’t have the spec completed; It’s not only non-standard but the spec isn’t even complete!

To date, he has created nearly every entry by hand himself … of which there are less than 300. This shows a lack of usage by the industry.

Additionally, if anyone trys to actually do discovery and search these apis, they will find out they cannot do it; they first have to REGISTER and get a token before being able to even search!

NOTE: As of 5/01/2024 this has changed. You can NOW search without a token but your searches are RATE LIMITED (unlike with apis-catalog which uses existing search engines)

CONS

• By keeping the discovery behind a closed door, it does not help agents/search engines find your API’s in any way and is the opposite of discovery.
• a database/site outage would take out discovery for all apis everywhere
• you have to resubmit your document everytime you need to make a change.
• no industry backing
• schema is non-standard
• requires token/registration to submit

STORY UPDATE (06/05/2025)

Mr Lane (the proprietor of APIs.io) provided a rebuttal in the comments … but then quickly deleted it so I thought I would take the time to show his arguments as well as my rebuttal:

To address his issues, lets tackle them one at a time :

Is APIs.io use of APIs.json a gated community?

The standard (ie api-catalog) can be searched and indexed by search engines whereas apis.io can’t.

Hence ‘closed door’ (aka ‘gated community’). API-catalog ENABLES everyones site to be indexable and searchable… whereas apis.io wants to own the data. This is why api-catalog is a standard.

Could a database outage at APIs.io Render It Unusable?

First, Mr Lane states it is all on Github yet it DOES THROW an sql exception… and Github does NOT do database hosting.

As you can see, they are not cleaning their data properly and you can see the SQL error in the RESPONSE.

Mr Lane is either unaware of how his own backend works or is choosing to mislead… or both.

Do you have to resubmit your APIs.json document if you make changes to it?

Initially your document has TO BE APPROVED. But after that, they HAVE added functionality for re-indexing… though I have yet to see new changes get uploaded for our test.

Does APIS.json have Industry Backing?

No. This is something mentioned by many others time and again…

“When you compare APIs.json to other API-related standards, the teams that create them are broad and represent various interests. Standards generally are a broad church. For APIs.json to be as successful as possible, it will mean extending the community to incorporate more interests and views.” — Chris Wood

In fact, this is why the api-catalog standard did not want to support it and why the lead on the OpenAPI project stated:

‘You mention HAL and APIs.json, in your draft, but HAL is not exactly an API catalog media type and APIs.json does not have much adoption or a spec published with a standards body.’ — Darrel Miller

Even AI Tools acknowledge that APIs.json is not what you would use for your API catalog:

Is APIs.json a standard?

Obviously no. See the above answer.

Does it require a Token to commit?

In Mr Lanes words:

‘and even when the API did, the site didn’t’. — Kin Lane

So he admits to the fact that this was up and he took it down or changed it.

Additionally

I REALLY don’t think having a 13,000 line file to document API’s is maintainable in ANY WAY!!!

Conclusion

There are reasons why the IETF turned down Mr Lanes APIS.json and moved in a different direction and I hope it is very clear to everyone. Discoverability is supposed to be open for all search engines and agents… not closed to just one persons personal database.

And I don’t thin anyone wants to be creating/maintaining a 13,000 LINE FILE to handle API documentation.