Write Test and API docs for creating an Overheard with JSON

When we write code specifically for another program to interact with our
program we are writing an
[API](https://github.com/codeunion/fundamentals-of-web-development/wiki/Glossary#api-application-programmable-interface).

Programs talk to other programs by exchanging data. In order to
exchange data, we have to decide:

1. What data structure(s) to expose/accept (i.e. what models and which of their
   attributes do we share?)
2. Where to expose these data structures (i.e. which paths?)
3. What actions to allow on these data structures? (i.e. which
   methods at which paths?)
4. What format(s) do expose/accept? (i.e. html? csv? forms? json?)

We've decided our API will accept and expose our `Overheard` model with
its `id` and `body` as
[JSON](https://github.com/codeunion/fundamentals-of-web-development/wiki/Glossary#json-javascript-object-notation).

For our very first API feature, we're going to let programs create
overheards by `POST`ing a JSON representation of their quote to
`/overheards`.

*phew*. Thinking through this is hard work! It's critical to spend time
thinking about what you intend to do as you write code. As I think about
what I want to do, I find writing documentation and feature tests help
me focus on the end-users interaction. This is why this commit includes:

1. Documentation for the people who will use our API
2. Tests that prove our code works the way we expect it to.

New Libraries
=============
`rack-test` - Rack Test is a small library that lets us send HTTP
requests to our application from our tests. Where `capybara``is for
writing tests which interact with our app via HTML, `rack-test` is for
writing tests which interact with our app via pure HTTP. Sinatra
provides a decent tutorial for [using rack test with
sinatra](http://www.sinatrarb.com/testing.html)

`json` - the `json` library comes with ruby. It's used to parse strings
of JSON into ruby hashes; or dump ruby objects into json strings.
Remove comments from previous commit
Create Overheard from JSON

You'll notice I had to change the tests here as well. I:

1. Didn't realize `rack-test` used it's own faux HTTP Headers
   ("CONTENT_TYPE" vs "Content-Type", "HTTP_ACCEPT" vs "Accept")
2. Wanted to verify that the response included a Content-Type header
   declaring it was `application/json`
3. Wanted to use `JSON.dump` instead of `to_json` because I find it a
   bit more clear what's going on and wanted to be consistent between
   the route and the test.
4. Fixed a broken variable name! Silly Zee!

This is normal. Improving your tests/documentation as you implement a
feature reflects your improved understanding of your application.

New Functions
=============

`JSON.dump` - Takes a ruby object and converts it into a string of JSON.
[Documentation](http://www.ruby-doc.org/stdlib-1.9.3/libdoc/json/rdoc/JSON.html#method-i-dump)

`Datamapper::Resource#attributes` - Returns a ruby hash of the data
stored in the database.
[Documentation](http://rubydoc.info/github/datamapper/dm-core/master/DataMapper/Resource#attributes-instance_method)

Within Sinatra
--------------
`request`, provides access to a ruby representation of the the HTTP
Request. You can then call methods on it like `form_data?` or `accept?`.
[Documentation](http://www.sinatrarb.com/intro.html#Accessing%20the%20Request%20Object)

`request.body.rewind` - Ensures `request.body.read` returns the entire
body.
[Documentation](http://rdoc.info/github/rack/rack/Rack/RewindableInput)

`request.body.read` - Provides the http body as a string
[Documentation](http://rdoc.info/github/rack/rack/Rack/RewindableInput)

`status` sets the HTTP status code of your response.
[Documentation](http://rubydoc.info/github/sinatra/sinatra/Sinatra/Helpers#status-instance_method)

`content_type` sets the Content-type HTTP Header on your response.
[Documentation](http://rubydoc.info/github/sinatra/sinatra/Sinatra/Helpers#content_type-instance_method)
Write test for invalid json overheard

This is very similar to the previous test; except it's testing the
*negative* condition. We want to:

1. Use an HTTP status code to declare the request was invalid
2. Provide errors as part of our response
3. *NOT* create an Overheard if it doesn't have a body
Ensure the overheard app has access to `json`

Ha! Our tests didn't detect a critical error! Because we `require
'json'` in our `test/features/helper`, it provides the application
access to the `json` library when running tests!

Automated tests will never replace exploratory and context driven
testing; as even experienced programmers make mistakes like this.
API documentation for erronous overheards

Documenting how our API deals with erronous requests can prevent a lot
of head scratching when someone writes some code to interact with our
API.

I also wound up verifying the documentation is accurate. Did you know
ruby's JSON parser barfs if you use `'` instead of `"` to surround the
key names? NEITHER DID I!
Provider errors on invalid API calls

When the overheard added via the api can't be saved; we want to let the
user know that there was an error and on which fields.

The Datamapper::Resource `errors` object is a kind of Enumerable; so
that means we can call `.to_h` to get the errors as a hash where the
attributes are the keys and an array of errors are the value. This is
perfect for our api consumers.

Unfortunately we're starting to get a bit of duplication that is kind of
nasty. We'll want to fix that soon...
Remove duplication in `post "/overheards"`

BAM. This refactoring:

1. Creates a helper for accessing request data, regardless of if it's
   passed in via a form or JSON
2. Removes a couple nested ifs
3. Removes the need for `post "/overheards" to know whether JSON was
   submitted or a form was submitted (though it still needs to know what
   kind of content the requester will accept)
4. Removes duplication of two calls to `Overheard.create`

Hopefully this makes the code a bit easier to read and understand.
Thoughts?
Merge pull request #9 from codeunion/user-may-create-overheard-with-posted-json

User may create overheard with posted json