Objective

Provide a simple and transparent mechanism for the copyright free sharing and collaborative design of API specifications, interfaces and data models.

API Growth and the Challenge of Interfaces

Web APIs are fast becoming a critical technology to enable integration between service providers and consumers on the Internet, both in business and public spheres. As the number of APIs increases, so does the potential for innovation in terms of applications on top of these APIs.

Unfortunately however:

  • Many APIs provide similar or related functionality but use slightly different Interface patterns, conventions in data models, or otherwise differ in ways often not important for delivery of the API's functionality. This requires fresh code implementations for each and every new API by consumers
  • Reuse of existing API Interface specifications and data models is often a legal grey area since there is no clear means for organizations to signal that such specifications are copyright free and available for reuse.
  • For APIs which may be re-used, there are rarely uniform service descriptions in machine readable formats such as Swagger, WADL, Google Explorer, or other formats available

Each of these factors means that as the number of APIs grow, the amount of code needing to be written to interface to them grows as a high multiple of the number of APIs. This is already beginning to lead to a vast amount of wasted work and will be a serious limiting factor in the long term growth and usage of APIs.

Establishing an API Interface Commons

In order to address these challenges, we propose the establishment of a public "API Commons" that enables anybody to declare API Interfaces (Method Patterns, Messages, Data Models and any other related construct) they have authored as reusable, modifiable and shareable by others. The objective is to enable:

  • Authors of interfaces to declare what is reusable in simple terms.
  • Others to adopt reusable interfaces.
  • Encourage sharing adaptations back to the public commons.

We anticipate the benefits of this to be for both individuals/individual organisations and for the growth of APIs as a whole and innovation in general:

  • For Individuals / Individual Organisations:
    • Shared interfaces will represent a growing resource of well crafted common interfaces.
    • Reusing shared interfaces will provide a clear legal status for APIs in use.
    • Shared interfaces that see adoption by multiple parties may grow over time to have associated open source server side and/or client libraries.
    • Shared interfaces will hopefully over time evolve to represent best practice in a given sector.
    • Donating interfaces to the commons and contributing to common interfaces creates awareness and increases the likelyhood of server and client libraries being written for an API - increasing adoption.
  • For API deployment as a whole:
  • Convergence on common interfaces in specific areas will lead to a radical decrease in the amount of fresh code needing to be written to interface to such APIs.
  • If successful, the API commons could reduce the amount of distinct interfaces/api definition to be a factor of 10 or even 100 smaller than the number of APIs operating worldwide.

Core Activity

Bring about the regular sharing of interfaces using clear legal terms for reuse, using the minimum that is needed. We expect this to include devising a means to signal reusability clearly, and ideally the provision of vetted legal copy.

Supporting Activity

Whilst the items in the above sections are necessary to enable and API Commons, they would only barely be sufficient. Hence in addition to this, the group listed below, also aims to:

  • Creation of a web registry (and potentially other mechanisms) to locate interfaces in the commons, as well as provide easy to access information on how to declare an interface in the commons and list it.
  • Ensure the registry is well structured and includes links to projects associated with different interfaces on Github, the Web or elsewhere which show adoption of each interface and active use.
  • Track news about the usage and adoptions of the commons to help adoption and best practice.
  • Provide support for conversation around how to adapt and evolve API/service description frameworks to be more modular and composable. (likely through working sessions at industry events).

What is "in" and what is "out"

Interface items that are considered part of the commons are: data models, call patterns, interfaces specifications and definitions of any type. Typically the interface commons DOES NOT cover:

  • Computer code creating the functionality that would be required to IMPLEMENT the server behind such an Interface.
  • Computer code creating the functionality that would be required to IMPLEMENT the client or clients for such an Interface.

On other words, the objective is to ensure re-usability of the INTERFACE DEFINITIONS and is agnostic about the sharing status of implementations of the interface.

The implementation / computer code items may be available as "open source" under a variety of licenses or as proprietary code, however their provision is outside of the scope of the API Commons. Our conjecture is that existing open source licenses and practice are sufficient to cover these. API Commons may highlight and promote such implementing computer code however where it is known.

Principles behind API Commons

The objective of the API Commons is to increase sharing and reuse - any activity described here-in is not-for-profit and is open for re-use:

  • Anybody can declare works they have authored to be in the commons.
  • In very narrow cases they may be able to assert the work of others is in the commons (e.g. orphaned copyright).
  • API Commons takes no legal position on the legality of any particular declaration, it simply provides guidelines as to how something can be signalled to be in the commons.

In terms of support activities, while the objective is to provide a registry of work in the commons:

  • Many such registries could exist.
  • Many organisations could promote uptake of the commons.
  • Debate on recommendations, support activities etc. shall be open, free and inclusive.

Challenges

We believe this is a valuable and worthwhile exercise, but that it will also be challenging to establish and encourage such a practice. Challenges include:

  • "Who's first" problem - creating momentum will be difficult early on.
  • Technically it may not be that easy to determine how to reuse a whole definition or parts of one - it is not clear how well existing machine readable formats can be adapted to support this, yet be able to reference which is in use.
  • There may be legal challenges in certain cases.
  • Marketing and promotion for awareness will be a challenge on limited budgets.

Visit the frequently asked questions (FAQ) page for answers to some of the common questions. If you don't find your answers, visit the Github issue management for this project, and submit your question there.