What Exactly Is API Commons?

Wed, 04 Feb 2015 00:00:00 +0000

As I travel around talking to folks about APIs, I spend as much time as I can educating folks about API Commons, and I’m constantly reminded how little people, who have even heard, and read about API Commons, really understand what it is. With this in mind, I will be regularly publishing examples of what API Commons is, to help onboard everyone to mine and Steve's (@njyx) vision of API Commons.

API Commons is a machine readable pointer to the license of your API. As I talk with folks, and watch videos like this one at APICon in UK, I realize how many misconceptions there are about it. Many folks emphasize the Creative Commons license we’ve chosen, or the listing of APIs we’ve had added to our version of the commons, by publishing an API Commons manifest, which references a CC-BY or CC0 license.

If you feel your API should be covered under an open source license, or covered by your patent, or not covered by any sort of license, create an API Commons manifest that points to your API, references your license, and you’ve created your own commons. Now you can spider, and aggregate any API providers who have used the same license, into your own definition of what is the API Commons.

API Commons is not an API directory. API Commons is not a push for copyright in APIs. API Commons is a machine readable format for taking a stance on the licensing (or not) of your API definitions, and data models. Please join us today, by letting us know your stance on licensing of your API, we’ve love to hear your voice, and better understand your stance.

Support For Only Two Creative Commons Licenses In The API Commons

Wed, 16 Jul 2014 00:00:00 +0000

When we first conceived API Commons, we were a little fuzzy about which of Creative Commons licenses API providers should apply to their API definitions. As long as a provider took a stance on API copyright around your API definitions, applied a Creative Commons license, we considered an API “in the commons”.

As time has evolved, and we've had time to reflect on the decision that the Federal Circuit Court handed down in the Oracle v Google case, we've adjusted our vision of what Creative Commons licenses should be applied to an API, and still be considered as part of the "API Commons".

Moving forward the API Commons will accept two types of Creative Commons license:

CC BY-SA - At a minimum we want API designers to be recognized for their work, and other designers to recognize original authorship when relevant.
CC0 - Ideally all API designers put their API definitions into the public domain, and wave all their copyright around API designs.

We feel pretty strongly that API definitions have to remain openly licensed, re-usable, even for commercial purposes. In a perfect world we wouldn't have to apply copyright at all, but in light of the Oracle v Google case we should take a proactive stance, and apply the copyright license that make the most sense.

API Commons acknowledges the rights of API designers to recognized for their works, but strongly believe that for the API economy to grow and flourish, API definitions have to be re-usable, shareable and interoperable—publish your APIs into the API Commons today.

Fixing The Machine Readability in API Commons

Wed, 09 Jul 2014 00:00:00 +0000

When I first published 11 simple API definitions, I had developed using schema.org, into the API Commons, I made a mistake when I referenced the Swagger specifications for each of the APIs. I linked to the machine readable Swagger spec, but not the raw JSON stored on Github, errorneously I linked directly to the Github page.

I want the machine readable API datastore, at API Commons, which is used to drive the API listing page, to be completely machine readable, referencing all APIs, their machine readable API Commons manifest, as well as machine readable API definition. As the smart folks over at APIMatic pointed out to me, I had been flip-flopping on this. Some of my later entries were machine readable pointers, but my earlier entries were not.

Now all of the entries in the commons, have machine readable references to both their API Commons manifest, and API definition. I've also added a “format” page, to explain each of the fields, in the the API Commons manifest format, to help API providers better understand, and not make the same mistake I made.

The API Commons manifest is meant to be a standalone, machine readable pointer to an APIs central truth (a machine readable API definition), and associated CC-BY-SA or CC0 licensing, and now, I think we have achieved our original goals around making this happen.

API Commons Added To The API Commons

Thu, 05 Jun 2014 00:00:00 +0000

Even with the risk of possible creating some sort of API wormhole, I just added the API Commons API to the API Commons. The API for adding and searching for APIs that are in the commons, now has an API definition that is publicly declared as part of the commons, with a CC-BY license.

It just makes sense to have the API for the commons in the commons, so anyone can establish their own commons, complete with common API. 3Scale and API Evangelist are taking a particular stance on the API copyright discussion, and if our approach doesn’t match your vision of the API economy, we encourage you to fork and establish your own commons.

We only launched the API Commons API two months ago, so the definition is still fairly new, and we would love to hear your thoughts on the API definition, and the underlying format of the API Commons Manifest. It is up to all of us to help keep the surface area of the API economy as open, accessible, reusable and interoperable as possible.

Nothing Has Changed For API Commons In Light Of Oracle v Google Decision

Wed, 14 May 2014 00:00:00 +0000

While we definitely are concerned by the response from the federal court in the Oracle v Google case, but for us at API Commons nothing has changed—it just turns up the heat. The precedent for applying copyright to web APIs is far from settled, this will be a long legal road that will play out over years, during which the mission of API Commons remains the same—encourage as many API providers as possible to publish API definitions into the commons, accompanied with a liberal creative commons license.

The API sector and all derived areas (which is huge), would be better off without copyright being applied to a technological area that depends on re-use and interoperability, but if companies like Oracle want to be able to add yet another layer of control and monetization to APIs—let’s beat them to it and openly license the best API patterns in a way that acknowledges API designers, but also encourage the widest re-use possible. There are seven separate Creative Commons licenses to choose from, and we encourage putting it into the public domain, which despite popular belief still gives you copyright control over your designs.

Join API Commons and the entire API community in taking a stand on the API copyright issue. Publish your API definition into the commons, choose a creative commons license that meet your business and organizational goals. We have faith in the API communities belief that APIs designs are meant to be interoperable and reusable, and our ability to stay ahead of those who believe otherwise, by generating the best possible API design patterns and making sure these definitions are accessible by everyone!

Nothing Has Change For API Commons In Light Of Oracle v Google Decision

Wed, 14 May 2014 00:00:00 +0000

Nothing Has Change For API Commons In Light Of Oracle v Google Decision

Green Button (Energy) API Added To API Commons

Wed, 07 May 2014 00:00:00 +0000

One of the most meaningful API projects I work on with the US government is the Green Button API, which provides access to energy data for US consumers across the country. First, what is the Green Button API? The Green Button builds on top of the Green Button data initiative which is:

...an industry-led effort that responds to a White House call-to-action: provide electricity customers with easy access to their energy usage data in a consumer-friendly and computer-friendly format via a "Green Button" on electric utilities' website.

Which Todd Park, Assistant to the President and U.S. Chief Technology Officer states:

Giving residential and commercial customers secure access to their own energy data in a standard, easy-to-understand format will help them visualize their energy use and identify opportunities to save money. At the same time, Green Button is spurring the development of new online tools and services that add value to this information, creating an innovative new domain for entrepreneurship and job creation.

The Green Button API delivers flexible access to Energy Usage Information through a set of RESTful interfaces, providing access any consumers Green Button data. The Green Button API is being designed by EnergyOS, providing a solution that any utility can download and run to mediate access between their retail energy customers, and 3rd parties who will provide energy data driven services to them.

I’m very excited to announce that the Green Button API definition has been added to the API Commons. The Green Button API represents why 3Scale and API Evangelist launched API Commons, to provide a place where we can hang the most important, and meaningful API interfaces, and underlying data models, to encourage re-use.

You can find the Swagger specification for the Green Button API on Github, complete with interactive documentation and other resources. The project is a work in progress, with the final specification still being hammered out by EnergyOS and utilities across the country, but the API is fully functional, and since it is on Github—the entire project is open for comment.

If you’d like to know more about the project, feel free to contact me directly at @kinlane or @apicommons.

Adding Evercam.io To The API Commons

Mon, 07 Apr 2014 00:00:00 +0000

The Internet of things (Iot), and security camera API platform evercam.io has submitted the API definition for their camera API to the API Commons.

I’ve been impressed with the amount of leadership that is coming out of this new startup in a potentially very political, and inevitable aspect of the API economy—cameras.

Marco Herbst (@marcoherbst) of evercam.io approached me during #APIStrat in Amsterdam and expressed interest in submitting their Swagger API definition into the commons, and this last weekend we created the API Commons manifest and published to the commons.

When I spoke with Marco several months ago about API Commons, he took the importance of submitting an API definition to heart. By doing so evercam.io is saying that their API definition is significant in their industry, and something that others in the industry should follow.

This type of stance in an industry like Iot is going to become crucial in encouraging not just manufacturers to adhere to a common format, but also saving application developers and data scientists time when their are building Iot solutions.

Thanks evercam.io for sharing your API definition with the world, and taking your role and responsibility in defining an interface to a very important layer of the API economy, so seriously.

Added API For Searching And Adding API Definitions To API Commons

Mon, 03 Mar 2014 00:00:00 +0000

I think the title of this blog post has the most occurrence of API, I’ve ever used. We have had requests to provide an API for the API commons, so now you can add API definitions using a Github manifest, the API Commons Manifest generator, or via the API Commons API.

I added the ability to search API definitions, as well as POST an API through the new interface. I deployed a simple registration form for the API using 3Scale API infrastructure, and will add more account management features as the API matures—right now can just signup, login, get your keys and logout.

If you’d like to integrate the publishing of API definitions directly to the commons from your API management system let us know, we are happy to help you with the integration, and keeping the latest version of your API definitions published to the commons automatically.

If you run into any issues or have comments you can submit via the issue management for the Github repository that the API Commons site runs in.

When To Submit API Definition To The API Commons? Earlier or Later?

Mon, 13 Jan 2014 00:00:00 +0000

I had a great conversation with a company developing some very interesting API designs, and upon talking with them about submitting their API definitions to the commons I got a common question: When should we submit our definitions? Now or later? They will be changing often.

Of course each API development team will be different, but my recommendation is submit early on. The sooner the better. Even if your API definition changes often, it is better to showcase the design, soliciting feedback from the community, and establishing a precedent within your industry now.

You can see this in action with the Free Application for Federal Student Aid (FAFSA) API. It is an initial API definition for a potentially very complex PDF form that the Department of Education uses. As soon as the API definition was published, it was made open via Github, looking to solicit feedback from government, developers and anyone involved in the FAFSA project. This has opened up quite a bit of discussion and participation in the design from several companies, developers and allowed the overall design to move forward in new ways.

When it comes to your API design it is ok to iterate, but without sharing these stories within your industry, you run the risk of reinventing the wheel, and doing work without first receiving feedback from potential consumers, missing critical opportunities to partner with key players, and so much more. Of course, evolving your API design out in the commons takes a humble approach to API design, but ultimately you will be healthier for it.

Your API design will never be done. Why wait for some unknown date, that may never happen. Get your API definition into the commons, make your mark on your industry, open up conversation and lead with your API. To be in the commons you just submit a manifest which acts as a pointer to your API definition, allowing your definition to change as much as it needs.

We encourage you submit your API definitions to the API commons now, rather than later, and then you can confidently move forward with the iteration on your API, knowing you have declared your API design to be open licensed, and a meaningful design worth following.