A Proposal for APIs.json Version 0.17

We have posted a draft proposal for APIs.json 0.17 based upon the work we've been doing with APIs.io over the last couple of months. The project has been dormant for a while, but with renewed investment in APIs.io, we are finding a need for new properties of the API discovery format.

This release is primarily about adding two new properties that play a role in APIs.json, APIs.io, and API Evangelist all working together to map the API landscape.

  • aid - A unique identifier at the collection and api levels.
  • overlays - References to collection and api level overlays.

After that we are adding a handful of property types that API producers can use to index their API operations:

  • GettingStarted
  • DeprecationPolicy
  • GraphQLSchema
  • Integrations
  • OpenAIPluginManifest
  • PostmanWorkspace
  • ServiceLevelAgreement
  • Versioning
  • Webhooks

These property types were identified profiling 75 APIs published to APIs.io, distilling what API producers are doing to manage their operations into properties that any API producer can use to index their operations..

You can see the latest version in use in the APIs.json Artisanal project, for two of the top API producers out there:

We'd love to hear any feedback on the spec, as well as the properties we are adding to the specification this round. We are learning a lot about what is needed from building APis.io, but would love to learn from other applications beyond just search.

The APIs.json specification is managed by Steve Willmott and Kin Lane, and we welcome contributes and feedback from the community.


The Future of APIs.json (2020 Edition)

This website and the conversation around APIs.json has been dormant for a couple of years. This was due to acquisitions, job changes, and just not enough time to invest in the specification beyond just putting it to use. Even though we haven’t iterated upon the version in a couple years doesn’t mean it has been put to the test when it comes to indexing internal and external APIs. With all this work, and a renewed energy in APIs, 2020 it feels like just the right time to get back to investing in the spec, and make recommendations for what the future of the APIs.json should look like.

API discovery still hasn’t been fixed as part of the overall API lifecycle, and more companies are just resorting to trying to make sense of the chaos after the fact, by indexing OpenAPI, log files, and other artifacts from across the API lifecycle, but alongside this madness there is also renewed interest in having a machine readable index of not just the OpenAPI and Swagger artifacts laying around, but also the other critical parts of API operations. Even with the growth in the adoption of Swagger and OpenAPI, these APIs specifications do not address the need for developers to find pricing, plans, rate limits, terms of service, documentation, SDKs, and the other building blocks of API operations. Resulting in a steady stream of questions from the community about what is APIs.json, and whether it might help us make sense of what is going on.

In 2020 we have refreshed the website for APIs.json, and [working on a proposal for version 0.16 of the specification](http://apisjson.org/format/apisjson_0.16.txt). This version includes some additional details for properties including name and media type, as well as opening up the conversation for a YAML edition of the spec. I have been pushing the specification in recent years to act as not just an index for individual APIs, but also for catalogs of APIs, and for blueprints that help you deploy templated APIs. As I push forward these conversations I am finding that having my APIs define as yaml is pretty critical to make the conversation more inclusive to business stakeholders, leaving conversations around the APIs.json nme pretty humorous. Opening up the doors for both JSON and YAML editions of the API discovery format, both leaning on the core specification to define what is possible with actual implementations.

Refreshing the website, updating the blog and Twitter account were the first business items on the list. Next we want to continue the conversation around the next version of the specification, getting us closer to an official 1.0 version that the community has helped define. There is still a lot of work to be done on the tooling side of things. There are a handful of open source tooling developed around the specification, as well as a growing number of API providers who have adopted the specification, but there is still a ton of work ahead to help make the specification something that is seen as the defacto API discovery format. We’ll continue going through the specification, as well as working on the available search engine, catalog, and toolbox implementations that put the specification to work. If you are using the APIs.json specification, or have comments and feedback about what the roadmap should look like, [please head over to GitHub issues for the project and share your thoughts](https://github.com/apis-json/api-json/issues). We look forward to hearing from you about what the future of APIs.json, and now APIs.yaml format might look like.


APIs.json Is An Index For API Operations

As part of the latest wave of work around the APIs.json format We wanted to take some time to help folks better understand exactly what APIs.json is, and what it can do for API providers, consumers, as well as the fast moving API sector. We are working on version 0.16 of the API discovery format, and we wanted to help get the word out about some of the cool stuff that is being done with APIs.json, as well as what is possible in the future.

What is APIs.json? APIs.json provides a machine readable approach that API providers can put work in describing their API operations, similar to how web site providers describe their websites using sitemap.xml. Here are the APIs, who are describing their APIs using APIs.json:

APIStrat Austin API
API Evangelist
Acuity Scheduling
BreezoMeter
CheckMarket
Clarify
Data Validation
DNS Check
Email Hunter
FeedbackHub
Fitbit
Gavagai
Kin Lane
Link Creation Studio
OneMusicAPI
Pandorabots API
Qalendra
RiteTag
Singlewire
SiteCapt
SiteCapt
Social Searcher API
Super Monitoring
Timekit
Trade.gov
Twitch Bot Directory
EnClout
frAPI
Section.io
Spoonacular

These are the API providers who have crafted their own APIs.json file, and have registered them with APIs.io. We consider these the authoritative version of the APIs.json, but as you'll see in future blog posts, APIs.json is not limited to just the API provider--API consumers can also craft their own APIs.json files describing 3rd party APIs that they depend on.


Setting rel=api Into Motion With Latest APIs.json Release

Bruno Pedro (@bpedro) who has been building APIs.json into his API Changelog service, made a pull request to the specification recently, pushing forward the link relation conversation for APIs.json. As listed in the specification, we have long intended to make APIs.json an official media type:

3.5.  Media Type

It is intended that if there is sufficient traction, the media type "application/apis+json" will be   submitted to IANA as per RFC: http://tools.ietf.org/html/rfc4288

However when it came to expressing your APIs.json as a link relation, we didn't even really have a plan in our road-map, resulting in a very generic allocation of a link relation for APIs.json.

3.8. Link Relation

 In order for an API to reference its own description, it is recommended that it include header or in-line references to the APIs.json file using the existing described by link relation:

[Note, this is a generic link relation but seems to fit the bill]

What Bruno is suggesting that we get a little more precise when it comes to our link relation, something the rest of the governing group for APIs.json agrees with. Here is the last update to the link relation:

3.8. Link Relation 

In order for a Web site to reference its API description, it is recommended that it includes a header or   in-line reference to the APIs.json resource using the api link relation, e.g.: 

It is intended that if there is sufficient traction, the link relation “api” will be   submitted to IANA as per RFC: http://tools.ietf.org/html/rfc5988

As with the media type, we intend to submit the link relation to Iana, per its RFC. Bruno's pull request sets in motion the formal link relation, but then also escalates the media type submission as well. 

With the interest and usage we have seen in the first year of the specification, we are confident the API discovery format will get traction. We are already seeing exploration around the link relation, achieving RSS like experience in the browsers, when visiting websites that have an active API program.

I have added a link relation to my API Evangelist, Kin Lane, and Master API project, all pointing to my central APIs.json, which provides an index of not just each of the APIs I use to operate the API Evangelist network, but also the supporting building blocks of API operations like pricing, support, etc. 

Thanks Bruno for the pull request, pushing out a minor release of the APIs.json spec, moving us to 0.15. This release primes the pump, for a queue of APIs.json requests that are in the works, like more API property types, country origin, and much more. 


Quantifying A Minimum Viable API Footprint Definition As Real APIs.json Driven Portal

I wrote a post the other day laying out what I'd consider a minimum viable footprint for API operations. My vision of just exactly what an API is, has gone beyond just the technical, ever since I started API Evangelist back in July of 2010. Early on I saw this was more than just about the API endpoints, and documentation, code samples, and many other building blocks were essential to the success (or failure) of any API platform, area, or ecosystem.

This recent post was an attempt, here in 2015, to quantify what I would consider to be a minimum definition for API operation. After writing it I wanted to take another stab at actually creating a portal, that would stand up to the API rhetoric that I regularly produce. What better place to start, than my own personal master API stack, where I am working to get control over my own infrastructure. Once I got a version 1.0 definition, I forked it, and setup a default API portal that I am calling my demo APIs.json driven portal.

I have published to Github, a version of my minimum API footprint, which I'm using APIs.json an engine. After looking at 10,000K+ APIs, I have a pretty good idea of what I like to see. This is my interpretation of all that monitoring of the space--a distillation of what I've seen while reviewing APIs. It isn't perfect, but neither is the space that we have, and my portal is just an attempt at quantifying what I'm seeing.

I'm going to create a minimum viable Internet of Things (IoT) version of this portal as well, and use APIs.json to deploy different interpretations of what constitutes a minimum viable API presence. If you have anything you'd like to see in my base template, let me know. If you want to fork and add to, then submit a pull request, even better. I'm just playing around, but also looking to establish a suite of APIs.json driven tools, that help me(and you), better understand the API space.

To help on-board you with my vision, I also added a walk-through for when you land on the site. Something I will be adding to when I have time.


A Breakdown Of My Dream APIs.json File

I'm continuing my work, to help people understand what APIs.json is, and the varying ways that it can be put to use. My post the other week, breaking down Fitbits APIs.json file is a good example of where to get started, and as a follow-up I wanted to help further set the bar for what a minimum viable APIs.json looks like, and today, I am going in the other direction--toward my dream APis.json file.

APIs.json starts with a basic set of descriptions for who you are, the API provider. Each header of an APIs.json file gives you a handful of parameters for describing who you are:

  • name - your individual or company name, who is managing the APIs.json file.
  • description - a description of your company and / or the API collection you are building.
  • image - an image, logo, or icon that describes yourself or your company
  • tags - a handful of key words and phrases that describe your API collection.
  • created - the first date in which an APIs.json file was created.
  • modified - the last date in which an APIs.json file created.
  • url - The url of where the APIs.json lives, allowing your file to be portable.

Those seven parameters provide details on who you are, and what the API collection is all about. Remember an API collection doesn’t always have to live under a specific company domain like Twilio.com, it could be a temporary or more permanent collection, that is part of specific project or application.

The next essential element of an APIs.json file, is the APIs collection, providing you the ability to describe one or many APIs as part of this collection. Similar to the parameters provided for the header, each API entry is allowed a handful of parameters that describe the API:

  • name - the name of the API.
  • description - a description of the value an API delivers.
  • image - an image, logo, or icon that describes an API.
  • tags - a handful of key words and phrases that describe the API itself.
  • humanURL - The url any human should visit to learn more about an API.
  • baseURL - The base url any machine should follow to start using an API.

Each API should have at least this information, at a minimum. I could stay here, with a minimum viable APIs.json definition, but I encourage you to take one more step, and put the properties collection to use for each API. You can provide any other URL you want for an APIs properties, but I recommend starting with the basic properties:

  • TermsOfService - where do I find your terms of service page.
  • StatusPage - where is the url of the status page, where I can get platform update.
  • Pricing - point me directly to where your pricing page is, so I can make a decision on price.
  • Forums - where is the community forum located for a platform, even if this is Stack Overflow.
  • AlertsTwitterHandle - what is the primary Twitter handle for the API itself.

These are meant to satisfy the common needs of anyone learning about API operations, however they are just URLs meant for the human API consumer. In my dream APIs.json file, there will be a robust amount of machine readable properties available for each API, beginning with the two most important:

  • Swagger  - a machine readable JSON or YAML file describing your API surface area
  • Blueprint - a machine readable markdown file describing your API surface area

Along with providing machine readable definitions of the API surface area, establishing a central truth or fingerprint for any API interface, it is just as important to provide a machine readable license for the API:

  • InterfaceLicense - a machine readable pointer to the licensing for the API interface

Along with making sure the interface of an API matches your application objectives, consumers need to understand the licensing restrictions, or the freedom that comes with deeply integrating an API resource into any system or app.

Since I’m talking about my dream APIs.json file, I’m going to talk about two added property formats I’m currently working on behind the scenes, adding to the stack of machine readable API definition formats.. These new areas, represent two areas I’m working hard to define and understand, right after I hand-craft Swagger definitions for my APIs:

  • API Pricing - taking pricing to the next level and making it machine readable.
  • API Questions - answering the important questions I need to know about each API.

Can you imagine if API pricing was machine readable by default? Think of the options for building in a broker or market layer within the index of API platforms, and API collections, or even via an IDE. These two definitions are in an alpha stage, but are based upon data I've been gathering behind the scenes, so a lot of thought has gone into settling on these buckets.

After that, I’d say there are a handful custom properties I’d like to see applied to each API indexed within an APIs.json:

  • x-blog - where do I find your blog. (machine-readable below)
  • x-blogrss - where can I just get an RSS of your blog stream.
  • b-github - what is the primary Github account for the API.

That concludes my list of elements I’d like to see available in my dream APIs.json file. You can see examples of this in action, with the 700+ companies I've generated APIs.json files for, over at my API Stack Github repo. There is a lot of work left to do, but this dream APIs.json file resembles a vision I have for the future of API discovery—which I see as the engine for the API economy.

My goal is to get there I need the most important aspects of API operations machine readable. We aren't there yet, but I can see it. Taste it. Imagine what we can do when you can program against:

  • Surface Area (Swagger, Blueprint)
  • Blog (RSS Feed)
  • Status (RSS Feed)
  • Forum (RSS Feed)
  • Twitter (Twitter API)
  • Github (Github API)
  • Pricing (api-pricing)
  • Licensing (API Commons)
  • Questions (api-questions)

I have been staying in tune with the API space using RSS feeds, and the Twitter and Github APIs for a couple years. I’m just now developing a deeper understanding of the overall API space through the generation of machine readable API definitions for popular APIs. I can’t do much on the API licensing front beyond launching API Commons, but I am working to define pricing with my api-pricing definition work, and also trying to capture the vital meta-data I need about API operations using api-questions.

This post ended up being longer than I anticipated, but it is helping me beter understand what some of the next steps are for not just APIs.json, but also my own monitoring of the space. My goal is to not just push forward the APIs.json definition, but push forward my understanding along the way. Who knows maybe I'll drag you along too! ;-)

Ok, back to work. I just needed to wrap up these two posts about APis.json that were lingering in my outgoing story and idea queue.


A Minimum Viable APIs.json File For Your APIs

I'm continuing my work to help people understand what APIs.json is, and the varying ways that it can be put to use. My post the other day, breaking down Fitbits APIs.json file is a good example of where to get started, but I wanted to help further set the bar for a minimum viable APIs.json.

APIs.json starts with a basic set of descriptions of who you are, the API provider. Each header of an APIs.json file gives you a handful of parameters for describing who you are:

  • name - your individual or company name, who is managing the APIs.json file.
  • description - a description of your company and / or the API collection you are building.
  • image - an image, logo, or icon that describes yourself or your company.
  • tags - a handful of key words and phrases that describe your API collection.
  • created - the first date in which an APIs.json file was created.
  • modified - the last date in which an APIs.json file created.
  • url - The url of where the APIs.json lives, allowing your file to be portable.

Those seven parameters provide details on who you are, and what the API collection is all about. Remember an API collection doesn’t always have to live under a specific company domain, it could be a temporary or more permanent collection, which is part of specific project or application.

The next essential element of an APIs.json file, is the APIs collection, providing you the ability to describe one or many APIs as part of this collection. Similar to the parameters provided for the header, each API entry is allowed a handful of parameters that describe the API:

  • name - the name of the API.
  • description - a description of the value an API delivers.
  • image - an image, logo, or icon that describes an API.
  • tags - a handful of key words and phrases that describe the API itself.
  • humanURL - The url any human should visit to learn more about an API.
  • baseURL - The base url any machine should follow to start using an API.

Each API should have at least this information, at a minimum. I could stop here, with my minimum viable APIs.json definition, but I encourage you to take one more step, and put the properties collection to use for each of your API. Using the properties collection, you can provide any other URL you want for an API--I recommend starting with four basic properties:

  • X-documentation - Where the documentation resides for the API.
  • X-signup - Where a user can signup to use an API.
  • X-pricing - What is the pricing for using an API.
  • X-tos - Where do I find the legalize behind AP operations.

Ultimately you can define any property you wish for an API, but recommend with these essential building blocks that all API consumers will need. After that each API has a contact collection, allowing you to provide some basic support for API operations:

  • FN - The name of person to contact.
  • email - The email address to contact.
  • X-twitter - A twitter user for the API.

These contact properties, follow the vCard format, and provide what API consumers will need to get support for an API. The same properties are available again for the overall APIs.json file, as a maintainers collection, which provide contact information for the overall APIs.json maintainer. This will often be a duplicate of information for each API, but allows for ultimately flexibility in aggregating many disparate APIs, into a single collection.

That is it. That is a minimum viable APIs.json definition. We now know who maintains the collection, and essential details about API operations. This goes well beyond just the technical definition of an API, and provides essential business and political elements of API operations, that all API consumers will need to be informed of, and are something that developers will often overlook.

With an APIs.json file, open source API search engines like APIs.io will be able to index your APIs, and any API directory like ProgrammableWeb can do the same. The definition of your API(s) is now machine readable, and is portable, allowing this definition to live on any website, or within any desktop, web or mobile application.


Breaking Down The Fitbit APIs.json File

The quantified-self API Fitbit recently added an APIs.json for their domain. Their usage of APIs.json is a perfect, dead-simple, introductory example of how APIs can start putting APIs.json for their API platform. To help other providers understand, I wanted to take a look at the moving parts of Fitbits APIs.json, and to assist the conversation I labeled each part.

A) The heart of an APIs.json, providing a name, description, image, and tags for API platform and collection.
B) The technical details of where this APIs.json came from, which version it is, and when it was created and last modified.
C) Similar to the overall APIs.json collection, each API gets a name, description, image, and tags, but also as the default URL people should go to find the API, as well as the base URL actually make calls to the AP, which is used as the API identifier.
D) Properties collection for the API. This is where the flexibility in the APIs.json comes in, and you can define any type of URL you wish. Ideally we establish a core set of machine readable properties, but providing human links to blog, documentation, etc are essential too.
E) X-blog - a link to the Fitbit blog, providing a direct link that users can use to read the blog.
F) X-blog-rss-feed -a link to the RSS feed, providing a machine readable link to stories, and updates for the platform.
G) X-github - a link to the official Github account for the Fitbit platform, when you consider the Github API, this becomes a machine readable link to multiple aspects of API operations.
H) X-twitter - a link to the official Twitter account for the Fitbit platform, which again, using the Twitter API, this becomes a machine readable resources for accessing platform communications, updates, and resources.
I) Contact information for the Fitbit API team, which they route you to a forum. Some platforms put their Twitter handle here, and others put an email or phone number.
J) Maintainer for the APIs.json, which since it is Fitbit, helps provide authority, showing this APIs.json comes from the source, and is not a collection built by someone else, which includes the Fitbit API.

The initial APIs.json from Fitbit is simple, and while there is potential for additions like a Swagger or API blueprint definition, or maybe terms of services, and client code, would be an excellent start.

So what now? What does this do for Fitbit?

It makes the definition of their API portable. It acts like a sitemap.xml for their API program, allowing search engines like APIs.io to index Fitbit along with other APIs. You can also develop embeddable widgets, allowing the API information to be displayed on any site, and using Github and Twitter APis, and the Blog RSS, you could also pull other relevant information for display, and search within the widget, on any website or mobile application.

We are just getting going with APIs.json tooling, that will help add to the benefits of having one. I know of several projects in the works, developing internal APIs.json search engines, directories, and when you include API definitions like Swagger and API Blueprint in your APIs.json, things get even better. I’m using APIs.json for microservice discovery, navigation, and indexing, and as a way to connect API interfaces with containers that deliver on the promise an API is supposed to deliver.

I am seeing more API providers begin to deploy APIs.json for their providers, and I have two of the leading API management providers about to release APIs.json as a native part of their API management workflow, with others in the works. It is good to see APIs like Fitbit see the potential of indexing their API operations with APIs.json, something where the benefits are only going to grow over the coming years, as new tools, and services emerge that depend on APIs.json for engaging in the API economy.


Using APIs.json For My Microservice Navigation And Discovery

I’m rebuilding my underlying architecture using microservices and docker containers, and the glue I’m using to bind it all together is APIs.json. I’m not just using APIs.son to deliver on discoverability for all of my services, I am also using it to navigate around my stack. Right now I only have about 10 microservices running, but I have a plan to add almost 50 in total by the time I’m done with this latest sprint.

Each microservice lives as its own Github repository, within a specific organization. I give each one its own APIs.json, indexing all the elements APIs of that specific microservice. APIs.json has two main collections, "apis" and "include". For each microservice APIs.json, I list all the properties for that API, but I use the include element to document the urls of other microservice APIs.json in the collection.

All the Github repositories for this microservice stack lives within a single Github organization, which I give a "master" repo, which acts as a single landing page for the entire stack. It has its own APIs.json file, but rather than having any API collections, it just uses includes, referencing the APIs.json for each microservice in the stack.

APIs.json acts as an index for each microservice, but through the include collection it also provides links to other related microservices within its own stack, which I use to navigate, in a circular way between all supporting services. All of that sounds very dizzying to write out, and I’m sure you are like WTF? You can browse my work on Github, some of it is public, but much of it you have to have oAuth access to see. The public elements all live in the gh-pages branch, while the private aspects live within the private master branch.

This is all a living workbench for me, so expect broken things. If you have questions, or would like more access to better understand, let me know. I’m happy to consider adding you to the Github organization as collaborator so that you can see more of it in action. I will also chronicle my work here on the blog, as I have time, and have anything interesting things to share.


My Experiences Generating API Server or Client Code Using Swagger

When you start talking about generating server or client side code for APIs, using machine readable API definition formats like Swagger or API Blueprint, many technologists feel compelled to let you know, that at some point you will hit a wall. There is only so far you can go, when using your API definition as guide for generating server-side or clienit-side code, but in my experience you can definitely save some significant time an energy, by auto-generating code using Swagger definitions.

I just finished re-designing 15 APIs that support the core of API Evangelist, and to support the work I wrote four separate code generation tools:

  • PHP Server - Generating a Slim PHP framework for my API, based upon Swagger definition.
  • PHP Client - Assemble a custom PHP client of my design, using Swagger definition as guide.
  • JavaScript Client - Assemble a custom JavaScript client of my design, using Swagger definition as guide.
  • MySQL Database - Generate a MySQL script based upon the data models available in a Swagger definition.

Using Swagger, I can get myself 90-100% of the way for most of the common portions of the APIs I design. When writing a simple CRUD API like notes, or for links, I can auto-generate the PHP server, and a JS client, and underlying MySQL table structure, which in the end, runs perfectly with no changes.

Once I needed more custom functionality, and have more unique API calls to make, I then have to get my hands dirty, and begin manually working in the code. However auto-generation of code sure gets me a long way down the road, saving me time doing the really mundane, heavy lifting in creating the skeleton code structures I need to get up an running with any new API.

I’m also exploring using APIs.json, complete with Swagger references, and Docker image references to further bridge this gap. In my opinion, a Swagger definition for any API, can act as a fingerprint for which interfaces a docker image supports. I will write about this more in the future, as I produce better examples, but I'm finding that using APIs.json to bind a Swagger definition, with one or many Docker images, opens up a whole new view of how you can automate API deployment, management, and integration.


REST API Design: Bridging What We Have, To The Future, By Organizing The JSON Junk Drawer

API storyteller J(a)son Harmon (@jharmn) has a new YouTube channel up called API Workshop. He's going to be publishing regular API design workshop episodes, with the latest one titled REST API Design: Avoid future proofing with the JSON junk drawer. J(a)son provides a nice overview of how you should be structuring the JSON for your API, focusing on the usage of key / value stores. Ironically he uses APIs.json as an example of why you SHOULD NOT use custom key / values within your JSON. What is ironic about this, is that he makes the case for APIs.json properties, giving me a great starting point for helping folks better understand APIs.json, and why properties are key to its evolution, and flexibility.

The process J(a)son outlines in the portion of this segment that referred to APIs.json, describes the lifecycle of an APIs.json property, towards becoming more of a "first class property". There are three phases of an APIs.json property:

  1. X-Property - A user defined property, allowing anyone to craft exactly the properties that matter to them
  2. Property - An official machine readable APIs.json property element, acknowledging its wide usage, potential as common blueprint
  3. "First Class Property or Collection" - Baking a property into the specification as default property of APIs collection, or establishing as sub-collection for the API

The lesson J(a)son provides, describes the journey of each APIs.json property, the difference is in that his lesson provides best practices for API providers who are designing new APIs, helping them avoid the creation of a junk drawer, and the APIs.json property format is being applied to define the junk drawer that we have (aka the public API space). This represents the fundamental separation between my approach to defining the space vs. many other technologists—I am trying to map out what we have, and get us the next step in our evolution, while others are working hard to define where we should be going.

When Steve and I originally hammered out the APIs.json format, we couldn't 100% agree on what should be first class properties and collections for each API defined using an APIs.json file—what you see in version 0.14 is what we agreed to, the rest needs to be defined by the community, through actually implementations and discussion on the APIs.json Github repo.

When you are crafting the JSON, for a new API, J(a)son’s lesson is very important, but when you are evaluating hundreds of APIs, and trying to define a common pattern for representing not just the tech, but the business, and politics of an API—you don’t have as much control over how things get defined. I’m not worried about the overhead involved with adding a little more complexity to my code, to bridge the well-defined aspects of API operations with the lesser-defined parts of the space.

Ideally, in one of the next iterations of APIs.json, the official properties of Swagger, RAML, Blueprint, and WADL can move up into a first class collection for each API called definitions, and maybe also consider moving API Commons up to be a first class licensing collection as well. I’m also looking to graduate some X-properties to official status, based upon creating APIs.json for over 700+ companies, and having identified almost 150 separate properties that can be used to describe API operations. All of this represents the API sector coming into focus, and I do not think all of these properties should become "first class" properties or collections—I am just trying to make sense of the "junk drawer" that we have, and help provide a blueprint for a machine readable formats that can help us evolve it towards the future we want.

I have been asked by several folks to better explain Steve and mine APIs.json vision, and J(a)son’s story gives me the opportunity to help kick off this storytelling. In an effort to keep this story short, I’m going to follow J(a)son’s lead and move the rest of this story on to YouTube, so if you want to better understand APIs.json properties, you can watch my video response to J(a)son's story, which augments this post, and hopefully provides some better examples, along with narrative.


What Exactly Is APIs.json?

As I travel around talking to folks about APIs, I spend as much time as I can, educating folks about APIs.json. In the course of my evangelism, I’m constantly reminded how little people, who have even heard, and read about APIs.json, really understand about what it actually is. With this in mind, I will be regularly publishing examples of what APis.json is, to help on-board everyone to Steve (@ngynx), and mine vision for APIs.json.

APIs.json is an open format, in partnership between 3Scale and API Evangelist, to help API providers make their APIs more discoverable, assist API brokers in aggregating multiple APIs deemed valuable within specific industries, and ultimately empowering API consumers in finding exactly the APIs they need to be successful--with a mission to make the process of API discovery as portable as we can, enabling it to live on any website, and be found in open search engines like APIs.io.

APIs.json is a machine-readable description of your company, and its associated API resources. For each API listed, you give it a name, description, and supporting properties, which may be as simple as providing a link to your documentation, or be as complex as providing a link to a machine readable API definition in the Swagger or API Blueprint format. One APIs.json detail, that I feel many technologists overlook, is that this isn’t just discovery in a hypermedia context, this could only be about the discovery of your pricing orj just the terms of service page (I know, a hypermedia format can descibe this, but I think you are missing an intermediary step to get the space there!)

If you need an example of APIs.json file, a good place to start is the APIs.json for APIEvangelist.com, this provides a good default example of APIs.json working within a single domain. If you want to better understand how an API broker may use to build API collections, take a look at the APIs.json for my utility stack, which is a collection of APIs from various locations, brought together to serve a specific purpose. Beyond that, take a look at the 700+ APIs.json files I’ve created for top APIs as part of my API Stack—hopefully this will help you see it in action across hundreds of API resource.

Our goal is to encourage EVERY API provider to publish an APIs.json in the root of their public domain(s), but it can also be used in the same way for private APIs, so don't get hung up on the public aspect of all of this. Beyond these early implementations, I want people to also build API collections, and virtual stacks of the APIs for use in their own projects, beginning the process of building some valuable definitions of th emost used APIs in use today. Please join this evolution API discovery, and publish your own APIs.json file—I appreciate the help.


Next Stable Version of APIs.json + APIs.io Is Ready - Are Your APIs Discoverable?

Steve (@njyx), Nicolas (@picsoung), and I have been working hard to gather all the feedback from some very smart folks on the API.json format. Now we are stoked to finally announce that we have the 0.14 version ready for prime time. Our goal with the first version of APIs.json, was to just get the idea out there to get feedback from the community, and after four iterations, we feel like the format is now something the community can really build on.

First, lets recap, what is APIs.json? APIs.json is a machine readable JSON file that lives in the root of your domain, and describes your APIs and its supporting API program.

Think of APIs.json as a robots.txt, or sitemap.xml from Google, but instead of describing all the pages of your website, an APIs.json describes your developer portal, all available APIs, and the supporting building blocks of your API program--allowing you to describe your API efforts whether it is a public, or private affair. The goal is simply to provide a machine readable description, that any search engine can crawl, and make sense of your overall API program, and each individual API resource.

The real power of APIs.json lies in the properties that you can apply to your APIs. We wanted to start with providing basic links meant for humans, like a link to the API signup page, or documentation, but then quickly provide machine readable elements like a Swagger specification, or API Commons manifest. However we don’t want to define and control all of the properties you use to describe your APIs, and while we have a short list of additional properties that we are adding in on the next version, you can use any property you like just by adding x- to your own type label.

Along with the APIs.json 0.14 release, the API search engine APIs.io also supports the latest APIs.json format. You can now validate your APIs.json 0.14, and submit your API.json for indexing using the APIs.io interface or API (mind blown). Your APIs.json will be your gateway to API discovery in the future, and since APIs.io is an open source API search engine, it will just be the first of a wave of new API search engines to emerge, built on the APIs.json format.

While we will be making slight changes in coming versions of APIs.json, we feel like the format is now ready for prime time, and we encourage the entire API community to begin participating in the next generation of API discovery, where your API, and the details of your API program are machine readable, and discoverable, in a single, known location at your company, organization, or agencies  public or private domain.


Trade.gov Using APIs.json And Added To APIs.io

I've been a big proponent of APIs in the federal government, and it makes me really happy to see Developer.Trade.Gov using APIs.json to provide an inventory of APIs available at the federal agency dedicated to strengthening "the competitiveness of U.S. industry, promotes trade and investment, and ensures fair trade through the rigorous enforcement of our trade laws and agreements".

If you aren’t familiar with APIs.json, it is the open format that 3Scale and API Evangelist are working on to help make APIs discoverable. You can see APIs.json in action at the open source API search engine APIs.io, where the International Trade Administration (ITA) has submitted their APIs.json file for inclusion. ITA is the first of many federal agencies I will get to adopt the APIs.json format, and help make their valuable API resources much more discoverable, and ultimately more consumable.

Can you imagine a future where all global trade is machine readable by default, and there are millions of simple, discoverable APIs available to help stimulate, as well as regulate industry? A future where the Department of Commerce and other relevant agencies are at the center, with the highest quality APIs you can imagine, and the healthiest outreach to not just industry, but also individual business owners.

Trade.gov’s impressive entry into the world of APIs with Developer.Trade.gov, their quick responses to feedback, and the publishing of an APIs.json file for the agency, makes me optimistic for this vision of the API economy. If our federal government can do it, then I think industries can follow the lead, ensure that the future of trade and commerce is more real-time, transparent, and accessible to everyone.


An APIs.json Collection Of API Resources Across Your Public, Partner Or Internal Resources

APIs.json was designed to be a versatile API discovery format, not just a format for public API discovery via search engines like APIs.io. An APIs.json is meant to be a machine readable index of APIs within a single developer hub, providing information on the API endpoints as well as any other supporting resources--there is no reason that all of this can’t also be applied in a private setting.

APIs.json can easily be placed within a domain, subdomain, or at any network address, and be used to describe an internal collection of API resources, as well as bring in outside APIs. APIs.jsonbui excels at aggregating multiple, potentially disparate APIs, into a single coherent collection for use in development.

Using internal APIs.json files, a company, organization or governent agency can deploy an instance of an open source API search engine like APIs.io, or develop a custom API search tool that can aggregate the different APIs.json from each location, into a company wide API search and discovery destination.

An APIs.json provides a framework for referencing each APIs machine readable definition in Swagger, API Blueprint or RAML format, as well as other resources that internal developers will need to be successful, such as authentication info, SDKs, terms of service, and the multitude of other building blocks.

If you have public APIs, it will be a no brainer for you to generate machine readable API definitions for your APIs, and add them to a single, or potentially multiple APIs.json files for indexing. Even if you don’t have public APis, you can put APIs.json to work improving your internal API discovery, while also opening up your API resources to the other benefits of having machine readable API definitions.


The Power In API Discovery For APIs.json Will Be In The API URL Type

An APIs.json file lives in the root of any domain, or subdomain, and provides references to a collection of API resources. The APIs.json is meant to be a lightweight framework, where someone can build a collection of APIs, give it a name, description, some tags, and the APIs collection points you where you need to go, to get more information about those APIs.

For each API, you can define a list of URLs, each with a defining “type”, letting you know what to expect when you visit the URL. Right now, most of those URLs are just for humans, pointing to the developer portal, document, and terms of service (TOS). We are adding other API url types, that API search engines like APIs.io can expose in their search interfaces, like code samples, and application gallery, to the next version of APIs.json.

These human API URL types provide a reference, that API search engines can use to guide human users who are searching for APIs. However, where the real power of APIs.json comes in, is when an API URL type references a machine readable source, like a Swagger definition, or an API Commons manifest. When it comes to API discovery, we need as many meaningful locations, that we can point human API consumers to, but also machine readable locations, that will help make API discovery much more rich, automated, and precise.

Imagine when I can do more than just search name, description, and tags, by keyword, much like APIs.io works currently. Imagine when you can specify that you only want APIs that are in the API Commons, and openly licensed. Imagine when I can search for APIs that allow me to use all my HTTP verbs, not just GET. Now, go even more in the future, when I can search for APIs who have a specific allowance in their terms of service, with a machine readable TOS type for APIs.json.

This is where I want to take APIs.json, and ultimately API discovery. Machine readable API definitions like API Blueprint, RAML, and Swagger are the very first API URL type that helps automate API discovery, and the API Commons manifest is the latest. My goal is to tackle terms of service, pricing, and other critical aspects of API integration, and push forward a machine readable definition, that can ultimately be baked into the API discovery process--in all API search engines.

What is important to me, is that the API URL types, in each APIs.json, remain independent, and only loosely coupled with the APIs.json format, using a simple label, and URL. I’m not directly invested in the evolution of each Swagger version, however I am with API Commons, and potentially other future APIs.json API URL type definitions. I want anyone to be able to step up and suggest API URL types for the APIs.json spec, making APIs.json URL types a community driven API discovery layer, for the API economy.


Multiple Types of APIs.json For Discovery

I’m working through thoughts around a suggestion for future versions of APIs.json API discovery format, and as I do with other things I’m trying to make sense of, I wanted to write a blog post on API Evangelist. If you aren't familiar with the format, APIs.json is meant to be a machine readable JSON file that provides an overview and listing APIs available within a specific domain.

Authoritative APIs.json
This is an APIs.json that is made available in the root of a domain, that is providing detail on an API that is managed within the same domain. This use case is for API providers to list the APIs that they offer publicly.

Tribute APIs.json
There is an API you use, and want to see it indexed in an API search engine like APIs.io—so you create a tribute APIs.json. This APIs.json index is not done by the owner of the API, but by a fan, or outside contributor. Tributes will weave together the world of APIs, when providers do not have the time.

Facade APIs.json
There is an API you use, but doesn’t have exactly the interface you would want. Some resourceful API architects will be building facades to existing, external API resources. In the API economy you do not settle if an API isn't exactly what you need. The remix able nature of APIs allow for extending by designing facades that transform and extend existing API resources.

Cache APIs.json
If I learned anything working in the federal government last year, it is that APIs can go away at any point. In the future there will be a need for cached versions of existing APIs, providing redundancy and access to some important data and content.

Aggregate APIs.json
In fast growing areas of the API economy, we are seeing API aggregation trends, with sectors like social, media, cloud, financial, analytics, and other areas that have matured, and users are depending on potentially multiple API platforms.

Derived APIs.json
I envision derived APis as just an evolution of tribute or facade, stating that I started with a certain API design, but have evolved it beyond what it once was. Not acknowledging where we got our API patterns is a darker side of the API space that needs to go away—let’s be honest about where we learned our patterns and give a nod to these sources.

In the API economy, I think there will be multiple types of APIs that are deployed. As APIs proliferate, if the industry focuses on interoperability and reuse, there will be more types of APIs than the single API provider and APIs.json will help us keep tabs on this.

Not all API providers will have time, desire and the access to resources to publish their APIs.json, and the augmentation, replication and other possible derivatives that will emerge to organically expand on existing patterns.

Right now we are working on just stabilizing the latest release of APIs.json, so that people can get to work on publishing their own APIs.json. My goal with these thoughts is to just explore what is possible, and maybe, if successful some of these thoughts will be incorporated in future versions.


Solving The Problem Of API Discovery

API discovery has not changed much since 2005, when John Musser launched ProgrammableWeb, the API directory we've all come to know and love. In 2014 (9 years later), we have Mashape and a handful of other API directory and discovery tools, but we have not made progress on truly being able to discover the best APIs possible, in a distributed, machine-readable way.

Steve Willmott of 3Scale, and Kin Lane of API Evangelist, are at it again, looking to provide a possible solution, that we are calling APIs.json—a machine readable listing of your APIs and supporting building blocks that lives in the root of your domain.

The objective of APIs.json is to help fix this problem by making it easy for people to signpost where the APIs on a given domain are and provide information on how they work. The format is simple and extensible and can be put into any web root domain for discovery.

We are just getting started, so make sure and get involved via the Github repository or via the Google Group we've setup to facilitate discussion.


Announcing APIs.json At Gluecon 2014

One of our favorite events to attend is Gluecon in Broomfield, CO. Eric Norlin and crew has done an amazing job of pulling together the leading technologists, into an intimate venue, where they can discuss the latest technology that acts as the glue of the Internet.

Following up on our release of API Commons at Defrag, we will be announcing APIs.json at Gluecon. Eric’s events, both Gluecon and Defrag, provide an excellent forum for not just generating awareness of new technologies, but also stimulating the discussion that is needed to push these technologies forward.

If you are at Gluecon, we'd love to hear your thoughts on APIs.json, and the general topic of API discovery and how we can begin to work together and establish a solution that works for the entire community.