Add count API or parameter

[mlissner]

Well, OK, I admit it, I miss the counts that we used to have in the API. Let's add them back, but with some tweaks to make them better. We have two ways we can do this:

1. A count API that just provides the count for a query.

2. A count parameter on the existing APIs that either:

   • adds the count to the results like v3
   • just returns the count instead of the results.

The main reason we removed the count was performance and to enable deep pagination, but it makes it difficult to see if filters are working.

Thinking about this a bit, I think the better ergonomics are option 2. Adding a whole new API for this seems really annoying, so a better trick is to add a new GET parameter to all of our database APIs that returns the count instead of the results. That'd prevent people from turning it on for all results like in v3, which caused problems.

So imagine taking a query:

/api/rest/v3/opinions-cited/?cited_opinion=32239

That'd return the items that cite 32239.

But if you wanted the count, you'd just do:

/api/rest/v3/opinions-cited/?cited_opinion=32239&count=on

Which would return something like:

{"count": 3302}

Easy enough?

And we could guide our v4 users by providing a reference to the count URL in the normal response. So right now v3 returns:

{
    "count": 2287,
    "next": "https://www.courtlistener.com/api/rest/v3/opinions-cited/?cited_opinion=105221&page=2",
    "previous": null,
    "results": [
...
    ]
}

That's nice. v4 is the same, but without the count key. In v4 we could do:

{
    # Add the count here ⬇️ 
    "count": https://www.courtlistener.com/api/rest/v3/opinions-cited/?cited_opinion=105221&count=on,
    "next": "https://www.courtlistener.com/api/rest/v3/opinions-cited/?cited_opinion=105221&page=2",
    "previous": null,
    "results": [
...
    ]
}

Thoughts?