Linked APIs

A Linked API is an API that uses URLs [RFC1738] as primary identifiers of data entities, and for references to connected entities.

The benefit of using URLs is that we can deterministically fetch an entity representation from anywhere on the web. Usage of URLs for identifiers and for referencing, as opposed to: synthetic keys or other types of internal pointers, allows data entities to be externalized and linked across organizational boundaries, thus connecting API providers and breaking data silos.

A Linked API can greatly benefit from being a Hypermedia API, but strictly speaking, the two notions are addressing different aspects of API design.

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.

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!

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" }
    ]    
  }
}

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


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

Contributors: Mike Amundsen