Difference between revisions of "1481: API"

Explain xkcd: It's 'cause you're dumb.
Jump to: navigation, search
(Please don't be so clever)
(Explaining EIRS)
Line 23: Line 23:
  
 
The title text specifies an arbitrary maximum time window in which the client may access the server, but upon closer examination the time limit is in actuality the number of seconds in a day.  
 
The title text specifies an arbitrary maximum time window in which the client may access the server, but upon closer examination the time limit is in actuality the number of seconds in a day.  
 +
 +
The IERS is the {{w|International Earth Rotation and Reference Systems Service}} which every few years adds a {{w|leap second}} to June 30 or December 31, making these days with 86,401 seconds.
  
 
==Transcript==
 
==Transcript==

Revision as of 13:52, 2 February 2015

API
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.
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

Ambox notice.png This explanation may be incomplete or incorrect:
Please include the reason why this explanation is incomplete, like this: {{incomplete|reason}}

If you can address this issue, please edit the page! Thanks.

This comic describes the application programming interface (API) documentation for a website. Normally, an API is intended to be used by another program, so both input and output are meant to be easily machine-readable. The documentation then explains how to use the API from your program.

However, in this case, the documentation is explaining (in an obscure way) that the website itself can be used as a (inefficient and hard to develop for) API. Presumably, the XML mentioned is XHTML. The "requested data" is the actual content (e.g. a blog post) and the "documentation describing how the data is organized spatially" is CSS.

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) version of Rivest-Shamir-Adleman (RSA) encryption, whose key is stored in an X.509 certificate. Normally, the browser or operating system does this behind the scenes, so API programmers and users do not need to know these details.

The access limits section (in the title text) says that the API can be used for 86,400 seconds each day. This is really the total number of seconds in a day, rather than a limit set by the server. 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.

Or, explained in the same style as the comic:

This comic satirizes how any sufficiently convoluted text arrangement in the pursuit of making a meaning will misdirect persons from their original assumption of the intent of said text arrangement.

The title text specifies an arbitrary maximum time window in which the client may access the server, but upon closer examination the time limit is in actuality the number of seconds in a day.

The IERS is the International Earth Rotation and Reference Systems Service which every few years adds a leap second to June 30 or December 31, making these days with 86,401 seconds.

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.


comment.png add a comment! ⋅ comment.png add a topic (use sparingly)! ⋅ Icons-mini-action refresh blue.gif 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)