DRY: respond_with to assert status and body
DRY: JSON parse response body
Invert request and it following rspec_api_doc syntax

Notice that I'm using my branch that sets parameters to {}
more compact rsp-api-doc format with :id

I can justify this step saying that it's fine that we have to specs but
wouldn't it be great if this also served as documentation? Enter rspec
api doc. First make a commit WITHOUT grouping by /:id but only by
generating and showing the docs. Then add this nice thing
Better doc titles
Make tests more meaningful, less dependent on fixtures

now the problem with this test and documentation is that we are testing one
specific case, depending on the exact fixtures above! It would be much better
if you could tell our users what to expect IN EVERY CASE, not just with these
given fixtures. So they know for instance how to parse it. What do they get?
A JSON, sure, but is it an array? Or a hash? Which keys does it include? Which
types are the values in? All this information is very valuable to API clients,
and also if you know this, we can have tests that ensure that what we promise
to our clients is actually what happens. So let's start by the INDEX. We
don't need to test that the exact parsed JSON is [{"where"=>"Coachella", "year"=>2013}, {"where"=>"Woodstock", "year"=>1969}]
This is not very valuable or intuitive as a description, and the test is
dependent on the fixture. But what we can test (and describe) generically is:
1) we will return (in JSON) an ARRAY
2) each array item will be (in JSON) a HASH
3) each item will have the key "where" and a String
4) each item will have the key "year" and an Integer or nil.

Then, just specific to the fixtures above, we can check the size
Same thing for all the tests
DRY: Expect Hash or Array
we introduce has_attribute :where, String which means that
every request that returns resources Concert will always
have a key 'where' of type String (either in hash or array).

This is a very good documentation, and we also test it
automatically every time
Same with when, with the additional option that it can be nil
check attributes on every success with content, even without block

https://github.com/rails/rails/pull/7231/files
Use short codes for HTTP status
Move attributes in own helper
Move instance creation into helper

How to make this spec even more generic and good for documentation?

Let's talk about that not_to be_empty check. What exactly do we mean?
We mean that if we have some concerts in the DB then /concerts should
not be empty. Does not matter their content. Now, if we didn't have
them, the rest of the test would still pass, because it would check the
attributes of NOTHING. But then it wouldn't be a meaningful test. If
suddenly we changed the attributes, the test would not fail! In other
words, it is really IMPORTANT that whenever we run the test for INDEX
we do have SOME instances in the DB, otherwise we are not fully testing.
And even in the documentation, we would not have any example output.
In general, testing with NO items in a DB is just a subcase, we do want
elements so we can fully test. So we can write this:
First use of instances: .count
Another use: create
DRY: Take resource name from example
Failing idea on using instances.any :id

Explain that "before" is actually run after "example_request", so
this fails because by the time we call instances.any :id, the before
has not been called yet.

You can try by writing debugger both in the before and in the .any
This is the most complicated specs

We want to write code in a readable way but evaluated things in the
inverse order. We write "given_some_instances" outside of the examples
but they are "before" inside each example. But then we write the
lazy params before, and we want them to be evaluated after the before.

So it's all about Proc and instance_exec.

Note that request_params.dup is there because the do_request consumes
the parameters, but we want example.metadata[:request_params] to remain
the same inside the example
Add instance.none and expand to all examples

Now look at the get '/concerts/:id' example, isn't it pretty?