Update API definition

module2/lessons/apis.md

@@ -14,11 +14,25 @@ Then, watch [this video](https://www.youtube.com/watch?v=s7wmiS2mSXY)
 
 ### APIs
 
-At a *very* high level, APIs are rules that applications use to communicate with each other.
+In the broadest sense of the term, an API is the part of an application that other people interact with. Using the example from the video above, restaurant customers don't walk back to the kitchen and give their order to the chef directly. Instead, they give their order to the waiter, the waiter relays that information to the chef, and then the waiter brings the food back to the customer. In this example, the waiter is the API.
 
-We are focused on building Web applications, so we are mostly concerned with **Web Based APIs**. These types of APIs are so common that this is what most people are talking about when referring to an "API".
+You have already used the APIs of many libraries, though up to this point we have not discussed them as such. When you  use RSpec in your test suite, it would technically be accurate to say that you are using the API of the RSpec library. You don't go in and work directly with all of the classes and methods that make up the RSpec library, but instead only the methods included in the documentation that RSpec intends for other people to use. This collection of methods is the RSpec API, which is documented in the [RSpec API documentation](https://rspec.info/documentation/). If you go to that link and click on the latest version of the rspec-core library, you'll see examples that are very familiar to you.
 
-Since web apps communicate in HTTP, an API can be more specifically thought of as the format of HTTP requests an application accepts, and the format of data it returns.
+You can also see the term API used in this very broad sense in [this documentation of the Ruby language](https://rubyapi.org/), [these Rails docs](https://apidock.com/rails), and the docs linked from [this Capybara page](https://teamcapybara.github.io/capybara/).
+
+### Web APIs
+
+Why haven't we been using the word API up to this point if we have seen so many of them? Because 99% of the time, when web developers use the word API we actually specifically mean a web API. We do this so often that we generally reserve the term API to refer to web APIs.
+
+A web API can be described as _the subset of routes for a web app that the creators intend other programmers to interact with to retrieve data from the application_.
+
+Just like our waiter example above, we don't want to allow an external user to come access every part of our web application. Outside users aren't allowed to come back and give our database (the chef) orders! But there are cases where we want to allow other programmers to access certain information from our database in a format they can use efficiently.
+
+One thing to notice is that the API for our application does not include the routes that return the HTML pages that we have been creating up to this point. While it would be possible for other programmers to send requests to those routes and parse the HTML that is returned to pull out information (this is commonly described as web scraping), parsing HTML can be kind of a pain and there's very little guarantee that the HTML won't change when we redesign our website.
+
+For that reason, when another developer uses our API we return the information in a format that is easy for computers to understand. In our case, we'll be using JSON.
+
+Note that the _information_ that is presented at `http://www.ourapp.com/horses/1` will likely be the same as the information we get when we visit `http://www.ourapp.com/api/v1/horses/1`, but the first will be better formatted for human consumption and the second will be formatted to be easy to use by other programmers/applications.
 
 ### JSON