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.
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.
{ "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!
For an API to become a Linked API it has to:
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 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"1. 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.
{ "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"}
]
}
{ "article_id" : 58321,
"title" : "A Blog Post About Something",
"author" : {
"username": "johndoe",
"name": "John Doe",
"id": 14912949
},
"series" : 394
}
{ "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 }
]
}
}
{ "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" }
]
}
}
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
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.