API
This article is a stub. You can help the IndieWeb wiki by expanding it.
API is an abbreviation for Application Programming Interface. APIs typically implement a specific protocol and accept/return data in a variety of formats.
Why
Why use the term "API"? Because it sounds cool and powerful!
"API" as a term is regularly marketed by silos and big corporations in general at their own (often annual) conferences because they want you to use and become dependent upon their proprietary APIs.
How
Use the existing mf2 markup your website already contains as your API. Remember that we should always be human first and application second.
Criticism
DRY Violation
Most APIs provide information that is already present on web pages. Thus there are two unnecessary duplications happening.
secondary URLs
1. A secondary (API-specific) URL for the same (or similar) information
APIs are nearly always created in a whole parallel URLiverse for reaching the same exact content. URLs that start with "api." and then have paths similar to (but often subtly different from) the equivalent HTML / web pages.
RSS (and other legacy feed formats) are a common example of the problem of "side files" or content duplicated from HTML pages, but often with less information (and sometimes requiring more bytes to say it!), at completely separate URLs.
Related: API duplicitousness is now often accompanied by "native" App duplicitousness - i.e. when content-centric sites duplicate their content into a "native" mobile app and then prompt you to download it when you access their "mobile" site or access their site from a mobile device
Using content-negotiation (AKA conneg), a site could provide, at the same URLs, data in other formats consumed by machines like JSON. This article makes this clear:
- 2013-11-29 The lie of the API
However, conneg as recommended in that article, and any form of offering data from a page in a completely different format is a DRY violation of another sort, and also unnecessary (has been for almost 10 years). Which brings us to our second unnecessary duplication:
secondary formats
2. A duplicate version of same information, just in a different format
This DRY violation means more work for the publisher, and more fragility too.
On the contrary, the better approach is to simply use your website as your API (AKA "HTML is my API"), which you can do so by marking up the data on your pages that you want machines to also see with microformats.
Posts about "Your Website is Your API":
- 2013-01-30 recent HTML is my API summary, twitter threads[1][2]
- 2009-02-01 Your Website is Your API: Quick Wins for Government Data
- 2006-10-22 blog post Can Your Website be Your API? about presentation
- 2004-09-28 presentation: Can your website be your API?
API Key
Typical services require user of an API key to call their API. No such key is needed to access web pages over HTTP and thus this is seen as a hoop for developers to jump through.
See related post:
TOS requirements
Typical services require agreement to a terms of service (TOS) before they give you an API key you can use to call the API.
This TOS requirement typically comes with call frequency or usage limitations, and is often used as a hook for business development (bizdev).
See related post:
Snowflake APIs
Typical sites (silos) and services create their own unique API because they think their service is special (when typically there are numerous others like it). Thus they are called "snowflake" APIs.
This uniqueness means every time you want to code for a new service, you have to spend the time to learn their particular snowflake API.
A better approach would be for new services to adopt standard APIs (social standards) so they would "just work" with existing code that supports those standards.
Complexity
Because the consumption of APIs are intended for computer programmers rather than the wider public, API developers frequently increase the level of complexity of consuming the content.
While decreasing in popularity as of the time of writing (2013-11), there are still a wide variety of services that require the use of overly complicated standard protocols like SOAP.
Fragility
APIs are fragile for several reasons:
- Site providers break their APIs all the time in version changes. Twitter has a long history of this.
- APIs are ephemeral. They don't survive archiving or archives. In contrast microformats are part of the HTML and thus as long as you can get some HTML for something you parse it for microformats and get all the information that way.
See snowflakiness as a term for referring to the inherent fragility of snowflake APIs.
FAQ
Why are APIs so popular
Q: Why are APIs so popular? E.g. If you can say that your startup offers an (REST/JSON) API then many people start listening, seems to be kind of a prestige thing.
A: Because of cargo cult development. Everyone looks at Twitter and says "Oh, Twitter are doing it, therefore we need to do it".
A2: Some startups have a misplaced desire to slap a nasty TOS and lots of weird requirements on building something on top of what they're doing. More: http://tommorris.org/posts/2452
Are RESTful APIs actually RESTful
Q: Do so-called RESTful APIs actually conform to the principles of REST?
A: In practice no, in several ways:
- They fail to adhere to the principle of one-URI-per-thing. See "secondary URLs" above.
- E.g. if you have “api” as part of your API URL, you are failing to be RESTful
One important point of REST is that the method a user navigates around a website matches the method by which they navigate around the site API.
Sessions
API Related IndieWebCamp sessions: