Improve "basics" docs

[twosigmajab]

1. Document that 3-tuples can also be returned to include custom headers.
2. Improve "Todo" example based on how such an app would actually be written:
   • Combine TodoSchema and CreateTodoSchema, so that TodoSchema actually includes the description (not just the id), and make id a dump_only field, so that there's no need for a separate schema for the create_todo endpoint's request_body_schema.
   • Update create_todo to actually use request_body_schema.
   • Demonstrate (1.) by including a Location header in create_todo's 201 Created response, in compliance with the HTTP spec ("...the [new resource's] location being... the content of the Location header").

I actually implemented a real Todo list example app with Flask-Rebar using Flask-SQLAlchemy, which these changes are based on. Figured I'd finally try to contribute back some best practices I'm following that Flask-Rebar's docs aren't currently demonstrating.

[twosigmajab]

My pleasure, @airstandley! Note, all Travis jobs passed except one, but that looks like an ephemeral networking failure during the pip install (specifically pip._vendor.urllib3.exceptions.ProtocolError: ("Connection broken: ConnectionResetError(104, 'Connection reset by peer')"). It might be worth prefixing calls that require the network with a good old travis_retry (depending on what happens with #160:).

[airstandley]

@twosigmajab This is fantastic! It's a huge improvement.

However I'm against removing all references to RequestSchema/ResponseSchema; I'm completely pro adding documentation that discusses different philosophies on API design and when Schema may be more appropriate than RequestSchema/ResponseSchema, but for our basic 'QuickStart' guide I am strongly in favor of suggesting RequestSchema/ResponseSchema.

[gtmanfred]

Is this still needed? can we make sure it is up to date for flask-rebar v2.0?

Otherwise, i would like to close it to start clearing out the backlog.

[jab]

I think there are still some good improvements here that would be beneficial to merge, but I no longer work at Two Sigma, nor with Flask-Rebar, and at this point I would have to hand this off to the maintainers (or another external contributor). Hopefully someone is still interested in making these improvements.