Linked APIs

Linked APIs are APIs capable of operating on distributed data-sets, crossing organizational data boundaries.

Conventional APIs assume that all data is local — they can only provide interface to data that is maintained by the API provider itself. Linked APIs unbundle data storage from the API interface. The unbundling allows distribution of the data storage across organizational boundaries, thus preventing formation of data silos on the web.

Motivation

Linked APIs are a novel breed of APIs that fix a significant flaw with the current generation of APIs.

The problem with the current APIs is that: most APIs are, at best, creating narrow windows into solid walls surrounding the silo-ed data islands. Even the most well-known and large APIs – such as those provided by Twitter, Facebook or Google – only operate on the data that is within their own databases.

Compare this silo-ed response:

{ "article_id" : 58321,
  "title"      : "A Blog Post About Something",
  "author"     : {
      "username": "johndoe",
      "name": "John Doe",
      "id": 14912949
  }, 
  "series" : 394
}

vs. the Linked API response that doesn't assume linked resources are local:

{ "href"  : "http://mydomain.com/posts/linked-apis-definition",
  "title" : "A Blog Post About Something",
  "links" : [
              {"rel" : "author", "href" : "http://api.our-company.com/authors/johndoe"},
              {"rel" : "series", "href" : "http://api.different-company.org/someseries"}
            ]
}

You can see that in the Linked API example, any resource (e.g. author) can live in a remote API/data-source, whereas in the silo-ed example, data is assumed local, is referenced with local identifier.

To take Twitter as the example: there is a lot that you can do with their public API; but in the end all of the created content always resides on Twitter's servers. The same is true for Facebook, of course.

In that sense, current APIs create isolated, guarded data islands in the universe of the web. Which is very "anti-web" — the web was created in the spirit of decentralized equal participation. On the web, everybody publishes everywhere, owns their data, and then we have ways to reach that data through hyperlinks, rss feeds, activity streams, Google search and other methods. APIs have not really reached that stage of maturity, yet. APIs are highly centralized, in terms of data storage, and virtually none of them ever link to other APIs.

We need APIs that link to each other. Hyperlinks were essential for the growth of human web. They are equally essential for the Internet of Things ahead of us.

We can only truly have open and free data, if we jail-brake the data out of the silos that data is stashed-away at, currently. Linked APIs are the key to data freedom on the web. They are the engine of that freedom.

Let's get the engine cranking!

The Nuts and Bolts of How-To

For an API to become a Linked API it has to:

Use dereferenceable URIs^[RFC3986] as primary identifiers of all core data entities. Most common example of dereferenceable URIs are HTTP URIs, but any URI from any other schema can be used as long as it is a resource locator and not just a unique string.
Similarly, use dereferenceable URIs^[RFC3986] to establish links between entities.
Architect API back-end as an index of a distributed storage, rather than a system of record for the underlying data. Event Sourcing with CQRS are often-used implementation patterns to achieve effective data-storage, with such approach.

The benefit of using URIs for data connections is that it allows externalization of a data entity — we can deterministically fetch an entity representation from anywhere on the web via a URI. Usage of URIs instead of synthetic keys or other types of internal pointers, allows pointing to a data entity across organizational boundaries, thus connecting API providers and breaking data silos.

Linked APIs vs. Hypermedia APIs.

Linked APIs style of API design focuses on unbundling of data storage from the interface, in APIs, which has the affect of allowing APIs to operate on data-sets that are distributed across organizational boundaries. The benefit of such design is better distribution of responsibilities among data-set owners and API publishers

Hypermedia style of API design focuses on "simultaneous presentation of information and controls such that the information becomes the affordance through which the user obtains choices and selects actions"¹. The benefit of such design is increased flexibility and adaptability over time.

Both of the styles use hypermedia controls (e.g. hyperlinks) extensively so they are very complementary, but still orthogonal in their design focus.

Example

A Linked API Response

{ "href"  : "http://mydomain.com/posts/linked-apis-definition",
  "title" : "A Blog Post About Something",
  "links" : [
              {"rel" : "author", "href" : "http://api.our-company.com/authors/johndoe"},
              {"rel" : "series", "href" : "http://api.different-company.org/someseries"}
            ]
}

A Siloed API Response

{ "article_id" : 58321,
  "title"      : "A Blog Post About Something",
  "author"     : {
      "username": "johndoe",
      "name": "John Doe",
      "id": 14912949
  }, 
  "series" : 394
}

An UBER Response That Is Not a Linked API Response.

{ "uber": {
    "version" : "1.0",
    "data" : [
      { "name" : "article_id", "value" : 58321 },
      { "name" : "title", "value" : "A Blog Post About Something" },
      { "name" : "author",
        "data" : [
          { "name" : "username", "value" : "johndoe"  },
          { "name" : "name",     "value" : "John Doe" },
          { "name" : "id",       "value" : 14912949 }
        ]
      },
      { "name" : "series", "value" : 394 }
    ]    
  }
}

An UBER Response That Is A Linked API.

{ "uber": {
    "version" : "1.0",
    "data" : [
      { "rel"  : ["self"],    "url" : "http://mydomain.com/posts/linked-apis-definition" },
      { "name" : "title",   "value" : "A Blog Post About Something" },
      { "rel"  : ["author"],  "url" : "http://api.our-company.com/authors/johndoe" },
      { "rel"  : ["series"],  "url" : "http://api.different-company.org/someseries" }
    ]    
  }
}

Have Feedback? Leave a Comment:

comments powered by Disqus

How To Contribute

If you find a typo, or have a suggestion about this document, please either submit a pull request to the Github Repo where this page is hosted, or open an issue request

Contributors

Mike Amundsen

References

^1. Roy T. Fielding Architectural Styles and the Design of Network-based Software Architectures

Linked APIs Definition was originally coined by Irakli Nadareishvili in 2014 and is licensed under a Creative Commons Attribution 4.0 International License.