Editing 1481: API
Warning: You are not logged in. Your IP address will be publicly visible if you make any edits. If you log in or create an account, your edits will be attributed to your username, along with other benefits.
The edit can be undone.
Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.
Latest revision | Your text | ||
Line 8: | Line 8: | ||
==Explanation== | ==Explanation== | ||
− | + | {{incomplete| Can we cite any examples of web sites advertising APIs for URLs that don't seem properly engineered, and are essentially just designed for humans, with CSS?}} | |
− | + | This comic presents a web site designed for human readers as if it was a proper a machine-to-machine {{w|web service}} with an {{w|application programming interface}} (API). | |
− | |||
− | + | Normally, an API is intended to be used by a developer writing a computer program, so the output is meant to be easily machine-readable. The documentation explains to the developer how to use the API from their program. | |
− | + | In this case, the XML mentioned is {{w|XHTML}}. The "requested data" is the actual content (e.g. a blog post). | |
+ | However, "documentation" is used to refer (in an obscure way) to the part of the response which documents how the blog post is laid out and styled for human consumption, i.e. the {{w|Cascading_Style_Sheets|CSS}}, and perhaps JavaScript layout code. | ||
− | + | In order for a program to process a generic web site designed for human viewing, the program needs to use {{w|web scraping}} techniques, which often break when the web site design changes in subtle ways that a human might never notice. So developers much prefer to have proper APIs with well-defined machine-readable formats, stable interfaces and documentation that actually describes the semantics of the data. | |
− | 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 | + | The API keys section is a step-by-step description of how a web page is protected with {{w|HTTP Secure}} (HTTPS). The {{w|Transport Layer Security}} (TLS) protocol uses an {{w|Elliptic curve Diffie–Hellman|elliptic curve Diffie–Hellman}} (ECDH) key signed using {{w|Rivest-Shamir-Adleman}} (RSA) encryption, which is stored in an {{w|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 {{w|International Earth Rotation and Reference Systems Service}} (IERS) is the organization that decides when to add {{w|leap seconds}}, which account for slight anomalies in the Earth's rotation as compared to the {{w|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 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 {{w|Daylight Saving Time}} in the U.S. and {{w|Summer Time}} in Europe and some other places. This suggests that the web service tracks time via {{w|UTC}}. | ||
==Transcript== | ==Transcript== | ||
:[Cueball sitting at a desk staring at a computer screen.] | :[Cueball sitting at a desk staring at a computer screen.] | ||
− | : | + | :API Guide |
:Request URL format: | :Request URL format: | ||
:<nowiki>http://~~~.com/<username>/<item ID> </nowiki><!-- nowiki tags to avoid linking to a non-existent website --> | :<nowiki>http://~~~.com/<username>/<item ID> </nowiki><!-- nowiki tags to avoid linking to a non-existent website --> | ||
:Server will return an XML document which contains: | :Server will return an XML document which contains: | ||
− | :*The requested data. | + | :* The requested data. |
− | :*Documentation describing how the data is organized spatially. | + | :* 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... | :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. | :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. | ||
+ | |||
{{comic discussion}} | {{comic discussion}} | ||
− | |||
− | |||
− |