1481: API

|< < Prev Comic #1481 (February 2, 2015) Next > >|

API

Title text: ACCESS LIMITS: Clients may maintain connections to the server for no more than 86,400 seconds per day. If you need additional time, you may contact IERS to file a request for up to one additional second.

Explanation

This comic presents a web site designed for human readers as if it had an API (application programming interface) designed for machine-to-machine web service. An API is a set of instructions about a computer program, intended to be used by developers of other computer programs, so the two programs can interoperate more easily. The documentation explains how to send commands to the program, and how the output will be returned.

Many web APIs are designed to return data in XML format. But in this case, the XML is XHTML, a version of the language that is used by most web pages. The "requested data" is the actual content (e.g., a blog post), and "documentation" refers (in an obscure way) to the parts of a web page that control how it looks on the screen (e.g. CSS and perhaps JavaScript layout code). The "documentation" may also be DTD which tells the XML parser info about this particular XML format, i.e. XHTML.

In order for a program to process a generic web site designed for human viewing, the program needs to use web scraping techniques, which often break when the web site design changes in subtle ways that a human might never notice. Therefore, developers prefer to have proper APIs with well-defined machine-readable formats, stable interfaces and documentation that actually describes the semantics of the data.

For example, Google has an official API for version 3 of their YouTube web service. But developers who don't want to hassle with the required API key or the costs associated with its use sometimes just scrape the regular YouTube web site. So, someone could publish this comic with a YouTube URL as a convoluted hint to developers that there is an alternative to the official API.

The API keys section is a step-by-step description of how a web page is protected with HTTP Secure (HTTPS). The Transport Layer Security (TLS) protocol uses an elliptic curve Diffie–Hellman (ECDH) key signed using Rivest-Shamir-Adleman (RSA) encryption, which is stored in an X.509 certificate. Normally, the browser or operating system does this behind the scenes, so most web developers and users do not need to know these details.

The access limits mentioned in the title text says that the API can be used for 86,400 seconds each day. At first this may appear to be a strange arbitrary number; however, it is in fact the total number of seconds in 24 hours, essentially meaning there is no limit on most days. The International Earth Rotation and Reference Systems Service (IERS) is the organization that decides when to add leap seconds, which account for slight anomalies in the Earth's rotation as compared to the mean solar day. These leap seconds will mean that the website is available for one extra second occasionally, although IERS decisions are based on actual Earth rotation rates, and they of course wouldn't respond to requests for leap seconds in order to lengthen the number of seconds that a web site would be available for in a given calendar day. The API does not discuss the issue that some days have 23 or 25 hours due to daylight saving time in the U.S. and summer time in Europe and some other places. This suggests that the web service tracks time via UTC.

Transcript

[Cueball sitting at a desk staring at a computer screen.]

API Guide

Request URL format:

http://~~~.com/<username>/<item ID>

Server will return an XML document which contains:

• The requested data.
• Documentation describing how the data is organized spatially.

API Keys

To obtain API access, contact the X.509-authenticated server and request an ECDH-RSA TLS key...

---

If you do things right, it can take people a while to realize that your "API documentation" is just instructions for how to look at your website.

 add a comment! ⋅  add a topic (use sparingly)! ⋅  refresh comments!

Discussion

It seems like the current explanation is completely wrong. The XML file with data and information about it's layout is just /X?HTML/.141.101.104.77 06:45, 2 February 2015 (UTC)

There are a number of things that can be done in HTML that are not correct XML (like using <input> instead of <input />) meaning that the XML file must be XHTML. 141.101.98.141 13:44, 7 February 2015 (UTC)

And title text is about leap seconds. Sorry, I don't have time to edit the explanation myself. 141.101.104.77 06:47, 2 February 2015 (UTC)

I think the leap seconds reference may be related to this: http://money.cnn.com/2015/01/13/technology/leap-second/ Jdluk (talk) 12:04, 2 February 2015 (UTC)

My initial reading was that the "spatial arrangement" refered to the CSS file rather than to any in-text arrangement, though now I'm not quite sure. 199.27.133.35 07:33, 2 February 2015 (UTC)

Yep, I'm also for this CSS interpretation, but I'm not so doubtfully about it... :) 188.114.101.18 07:57, 2 February 2015 (UTC)

Well I think it's a combination of the organizational markup (div's and whatnot) *and* CSS. But I wonder if it even makes sense to get this technical about it. The point is that what you receive is the data you want plus some information that isn't the data *per se* but which tells you how the data is intended to be organized. It could be worded as "To use a blog as an example, you have the actual text of the blog post, and the code that determines where on the page that text goes." 108.162.210.43 15:27, 2 February 2015 (UTC)

I'll add that title text to my API docs. It's hillarious. :D Bentinata (talk) 07:35, 2 February 2015 (UTC)

Since when are TLS keys required for http://anything? Is this a mistake, or is it some subtle reference to embedded objects sometimes using https://? 108.162.254.126 11:25, 2 February 2015 (UTC)

I'm guessing it's just a mistake. 108.162.216.152 20:35, 2 February 2015 (UTC)

Does anyone else think that the "Explanation in the style of this comic" lines could be removed, or at least moved within the explanation? They make the explanation more confusing that it needs to be (which I know is the joke in the comic), but I'm not convinced. --Pudder (talk) 15:48, 2 February 2015 (UTC)

I'm the one who left it initially, but I've removed it now. It hasn't evolved to a real full explanation. 108.162.216.152 20:35, 2 February 2015 (UTC)

Might the x.509 portion refer to: Domain Name System Security Extensions so it's starting with a description of how to get the IP address of the server? 173.245.56.166 (talk) (please sign your comments with ~~~~)

The API URL format shows quite clearly that HTTP is used, not HTTPS. --108.162.216.54 18:14, 2 February 2015 (UTC)

Is there really a "trend of describing a web site designed for human readers as if it was a proper a machine-to-machine web service"? I'm a web developer, and I haven't seen evidence of any such trend. 108.162.216.152 20:35, 2 February 2015 (UTC)

Example?

The explanation says “Come up with examples of the kind of glorified api-like web site documentation he's spoofing.” A very good example is Google's YouTube API. They charge a fee for information requests, but have a daily amount of “free” requests. Like Cueball, you have to provide your personal key with every request. However all of the information available through the API, is more easily available for free, if you just load the page of a video. Formatted neatly in identified blocks, ready for import into another system. Rasmus (talk) 08:41, 3 February 2015 (UTC)

Interesting - thanks. I noted this in the explanation, but since Google has a real API and doesn't describe their regular pages as an API, I still wonder if there are better examples. Also, does Google perhaps limit such requests if they get a lot from the same logged-in user, or the same IP address? Nealmcb (talk) 17:58, 3 February 2015 (UTC)