Content Negotiation for APIs and the Web

APIs often seem like another one of those very technical acronyms that only the most technical people will care about. If you don’t aspire to be a software developer, why should you ever care about what application programming interfaces (APIs)? To push back on this notion I regularly push myself to make APIs more accessible to business users. I feel it is important that anyone who use the web daily as part of their professional career should possess a working understanding of the tool(s) they depend, and have a grip on how APIs aren’t some add-on to the World Wide Web we depend on each day--understanding that APIs and the web are one and the same. Over the last twenty years the web has became a fundamental aspect of how we do business online, and APIs are just the latest evolution of how the web is being put to use to use as part of the digital transformation businesses are going through across every business sector today.

The World Wide Web, commonly known as the Web, is an information system where documents and other web resources are identified by Uniform Resource Locators, which may be interlinked by hypertext, and are accessible over the Internet—with “documents and other web resources” being the bridge between APIs and the web. If you are using the web you can use APIs, as long as you understand one of the fundamental building blocks of the web--that you can negotiate “documents and other web resources” in the following information formats.

  • Hyper Text Markup Language (HTML) - Each time you use the web you are getting and posting HTML documents using the Internet. HTML is a machine readable format that renders each web page you view, helping make easier for humans to read in a variety of languages. While you may not write HTML or directly “read” HTML, you are using HTML each day as you make your away around to different web sites and applications across your personal and professional lives. 
  • Comma-Separated Values (CSV) - If you have used Microsoft Excel or Google Sheets it is likely you’ve imported or exported a CSV file, providing a portable machine readable document that contains data which is separated using commas. Storing data within a document that any spreadsheet or other application can open up the data and render it in a tabular field / row format. Striking a balance between data being structured and consumable by machines as well as human beings in a lightweight format.
  • Portable Document Format (PDF) - The PDF is a file format developed by Adobe in the 1990s to present documents, including text formatting and images, in a manner independent of application software, hardware, and operating systems. A format that survived the transition to the web, providing a common way of sharing text, images, and other graphics in a format that will render the same no matter who is viewing it—adding to the toolbox of data formats which can be shared online via simple web URLs.
  • Extensible Markup Language (XML) - XML is a markup language that defines a set of rules for encoding documents in a format that is both human-readable and machine-readable. The design goals of XML emphasize simplicity, generality, and usability across the Internet, but has widely been used only within IT and developer circles when it comes to sharing data in a consistent way between systems using web technologies.
  • JavaScript Object Notation (JSON) - Provides an open-standard file format that uses human-readable text to transmit data objects consisting of attribute–value pairs and array data types. It is a very common data format, with a diverse range of applications, such as serving as replacement for XML in desktop, web, mobile, and device applications. Offering a more lightweight, but still machine and human readable format that can be used to define data, content, media, and other resources being transmitted via the web.

These media types are the fundamental building blocks of the web, and represent how we make data available using the web, allowing for consumers to access data via a simple URL. HyperText Transfer Protocol (HTTP), the underlying protocol used by the World Wide Web and this protocol defines how messages are formatted and transmitted, and allows any web user to negotiate the format of the data they are accessing via a simple Uniform Resource Locator (URL), also known as a web address. You can negotiate to receive HTML, CSV, PDF, XML, or JSON data. While not all web sites offer all of these formats for each page, these are the most common formats in which data is made available via the web. Making data accessible via the web in a public or private way that anyone with the web address and proper credentials can view or download.

APIs are not just some new and exclusive thing for developers to access. APIs are just the next step in the evolution of the web, and those who are in the know, will have the edge over those who do not. There is no difference between APIs and the web. If you are using the web you are using APIs. You just either no how to negotiate the access you need to what you need, or you do not. HTML is designed to be human and machine readable. So are APIs. There is nothing standing between you and getting access to the data, content, media, and algorithms you will need in the course of your daily operations. APIs are not outside your reach, if you take the time to understand and stay in tune with what is happening behind the scenes of everything happening online today.