Making Sure My API Roundup Stories Are Machine Readable By Designing Them As APIs.json Collections

Making a list of valuable APIs has been a staple of my tech blogging for 10 years now, and as I work to find even more meaningful ways of defining the API space, I’m pushing the envelope on how I do API roundup stories. Instead of just finding a handful of valuable APIs, and providing an HTML list of them, I'm going to use APIs.json, to make sure all of my collections are machine readable by default.

For each API I profile, it is valuable to have a nice logo, name, short description, and a link to the developer portal. However I want to also make sure other valuable, machine readable resources are also present like Twitter, Github, and Blog RSS. This is just the start, I want each API to also have a machine readable API definition using Swagger and API Blueprint as well--all indexed using an APIs.json file.

I’m using APIs.json in two ways, as an index for each API, as well as an index for the overall collection I’m building--you will find the overall collection using the big {A} below, and each API has its own little {A}. To show you this in action, here is an SMS API collection I've built:


This is a collection of MSS APIs that are curated by the API Evangelist, as part of monitoring of the larger message API space. This collection is managed as an APIs.json file, providing access to APIs, and their supporting platform, in a machine readable way.

Clickatell is a privately held mobile communications company founded in 2000 with a presence in US and Africa.  Clickatell delivers short message service SMS services through its Clickatell Gateway to mobile phone users through more than 800 networks in more than 220 countries and territories. Clickatell provides a pay as you go, SMS unit based pricing model for developers to leverage when building applications.
Clickatell SMS

Clockwork is SMS API focused on allowing developers to get up and running sending SMS as quickly as possible. Clockwork only focuses on sending and receiving of SMS for developers through a modern web API platform. Clockwork provides a pay as you go, SMS unit based pricing model for developers to access when building their applications.
Clockwork SMS

Developer Garden
Developer Garden is the developer ecosystem of Deutsche Telekom, providing mobile focused services to developers. Developer Garden provides SMS and MMS messaging, voice call, speech-to-text transcription and location services via web APIs. Developer Garden provides free developer accounts, with a pay as you go, unit based model for purchase of API driven messaging services.
Developer Garden SMS API

Mogreet is a text message marketing platform focusing on the delivery of branded, rich media to mobile devices via MMS in over 175 countries. Migrate delivers SMS, MMS, media transcoding, and use lookup services via their API driven platform. Migrate also employs a pay as you go, unit based approach for charging for its services, allowing developers to scale based upon their needs.
Mogreet Messaging API

TelAPI providers developers with a cloud based telephony platform with advanced telecom features and customizations not available in other cloud communications APIs. TelAPI provides the ability to send SMS messages, and manage quote for each account. The platform also provides a free trial for developers, with pay as you go, unit based pricing to pay for services that go beyond trial access.

Twilio, the cloud communications company, is reinventing telecom by merging the worlds of cloud computing, web services and telecommunications. Twilio provides a telephony infrastructure web service in the cloud, allowing web developers to integrate phone calls, text messages and IP voice communications into their web, mobile and traditional phone applications. Twilio provides a pay as you go, unit based pricing for developers, including volume pricing for larger capacity applications.
Twilio Messaging API

This is all rendered using APIs.json, and provides all of the relevant links you will need to potentially get up and running with each API. You can use the APIs.json to further pull activity for each API using the Twitter and Github APIs, as well as via RSS. You can also programmatically evaluate, compare, and generate client-side code, documentation, testing, monitoring, and other essential elements using the machine readable Swagger definitions I’ve included.

In the future, each time I post a roundup of APIs blog post, I will publish the list of APIs, using this APIs.json approach. There is a lot of work still to be done in, identifying, and indexing APIs in this format, as well as clarifying more detail about each API, like underlying data models, authentication, and pricing, but having a standard approach is a damn a good start. This is the standard format I will be using for all my API Stack profiling--you can find a complete list of APIs.json files, and Swagger definitions over on the Github repository for the work.

As soon as I finish my API Blueprint tooling, I will also be providing each API in the API Blueprint format, as well as in Swagger, offering some variety, when it comes to understanding the surface area for each API. Instead of tracking on the number of APIs across the industry, I’m going to be tracking on the number of APIs that are fully defined, using APIs.json, providing full access to each API operations, as well as providing machine readable API definitions in Swagger and API Blueprint.