Difference between revisions of "1481: API"

Explain xkcd: It's 'cause you're dumb.
Jump to: navigation, search
(Transcript: complete, format)
(Explanation)
Line 12: Line 12:
 
The comic describes {{w|Application programming interface|API}} (application programming interface) documentation for a website. Normally, an API is intended to be used from a 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.
 
The comic describes {{w|Application programming interface|API}} (application programming interface) documentation for a website. Normally, an API is intended to be used from a 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 obtuse way) that the website itself can be used as a [inefficient and hard to develop for) API. Presumably, the XML mentioned is {{w|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.
+
However, in this case, the documentation is explaining (in an obtuse way) that the website itself can be used as a (inefficient and hard to develop for) API. Presumably, the XML mentioned is {{w|XHTML}}. The "requested data" is the actual content (e.g. a blog post) and the "documentation describing how the data is organized spatially" is {{w|Cascading_Style_Sheets|CSS}}.
  
The API keys section is a literal description of setting up a TLS session. Normally, the browser or HTTP library does this behind the scenes, so application-layer programmers do not need to know these details.
+
The API keys section is a literal description of setting up a {{w|Transport_Layer_Security|TLS}} session. Normally, the browser or HTTP library does this behind the scenes, so application-layer programmers do not need to know these details.
  
 
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 absolute maximal limit which any object may be in interaction with another object for the duration of a single terrestrial rotation. A process is specified that can be observed should one wish to increase this limit, consisting of contacting the {{w|International Earth Rotation and Reference Systems Service}} (IERS) to request an additional second. The joke here is the IERS decides on when to add {{w|leap seconds}}, which account for slight anomalies in the Earth's rotation speed as compared to the {{w|mean solar day}} (normally, the true day length is slightly longer than 86,400 SI seconds).
 
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 absolute maximal limit which any object may be in interaction with another object for the duration of a single terrestrial rotation. A process is specified that can be observed should one wish to increase this limit, consisting of contacting the {{w|International Earth Rotation and Reference Systems Service}} (IERS) to request an additional second. The joke here is the IERS decides on when to add {{w|leap seconds}}, which account for slight anomalies in the Earth's rotation speed as compared to the {{w|mean solar day}} (normally, the true day length is slightly longer than 86,400 SI seconds).

Revision as of 09:49, 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.

The comic describes API (application programming interface) documentation for a website. Normally, an API is intended to be used from a 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 obtuse 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 literal description of setting up a TLS session. Normally, the browser or HTTP library does this behind the scenes, so application-layer programmers do not need to know these details.

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 absolute maximal limit which any object may be in interaction with another object for the duration of a single terrestrial rotation. A process is specified that can be observed should one wish to increase this limit, consisting of contacting the International Earth Rotation and Reference Systems Service (IERS) to request an additional second. The joke here is the IERS decides on when to add leap seconds, which account for slight anomalies in the Earth's rotation speed as compared to the mean solar day (normally, the true day length is slightly longer than 86,400 SI seconds).

Or, explained in the same style as the comic:

This comic pokes fun at 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 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 each normal day, rather than a server time limit.

Transcript

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 acces, 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 "APL 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)