Why document JSON and XML?

- [Instructor] Let's talk about why you would document JSON and XML, and how it relates to API documentation. API stands for application programming interface. It defines how two pieces of software communicate with each other. There are several types of APIs, but for this course, I'm going to focus on web APIs. I'll give you an example of a web API. Let's say you're using a Facebook app on your smartphone. When you open the app, the first thing it does, is retrieve your friends' statuses. To do this, it sends an API request to the Facebook server, with data that identifies you, and says that you want to retrieve the most recent statuses. Then the Facebook server responds, and returns the data, with all of the statuses to display. This is different than when you go to the Facebook webpage on a browser, the server is only returning the data, not a full webpage. If you are documenting a web API, what do you need to cover? Any time a developer builds something that uses an app, they need to know what the request will look like, so that the server can understand it, and what the response will look like, so that they can make sense of the data. The first web API was created by eBay. If you think about using the eBay website, it works great for individuals, but suppose you're a company like a thrift store, and you have software that keeps track of your inventory. You have to manually move information back and forth between two places, the eBay website, and the accounting software. Wouldn't it be great if stores could use accounting software that put things up for bid on eBay, and kept a record of the final sale? eBay came up with this idea in 2005, now more than half of the items sold on eBay are through the API, and not the website. What makes APIs so powerful? There are several features I could mention, but let's just start with mashups. APIs let developers create apps that bring together data from different sources. For example, let's say you wanted to create an app that shows how to get to the nearest dog park. How would you use APIs to build this? Several cities now provide APIs that list where all the dog parks are. Google Maps provides an API that says how to get to a given location. Your app first calls the city API, then, once it has a location, it calls the Google API, and gets the directions. So with APIs, apps can bring data together in new ways that no-one has thought of before. There's a website called programmableweb.com, it used to keep track of all of the web APIs that are publicly available to use. Starting with eBay in 2005, there's been extreme growth up to 2013, where there are over 10,000 APIs, and these are only the publicly available ones, there are also ones just for company partners or internal use. I've talked to people in the industry, who believe that these numbers represent less than 1/10 of the APIs out there. And guess what? All of those APIs need documentation. Why do we need good API documentation? It's the same reason as why we need good end user documentation. Software development and writing are two very different skills, most software developers hate to write, and most are not very good at it. API documentation is somewhat different than end user documentation. You are writing for a software developer audience, and they learn and understand differently than the general population. Also, the documentation is almost entirely text. The most widely used text format for web APIs are JSON and XML. They're used to describe structured data, which is data that doesn't necessarily fit neatly into a table. If you think about a database table, or an Excel spreadsheet, you have two dimensions of rows and columns, where the numbers of cells are the same for each row, and each column. Structured data is more like a tree, where data can branch off from other data any number of times. Of the two formats, JSON is simpler, and uses less text for the same amount of data, but XML came first, and is still heavily used in the industry.