Add attorney filtering to the party endpoint

[mlissner]

In a discussion, a user was confused about why the party endpoint returns zillions of attorneys even though it is filtered to a particular docket. I was briefly confused too, and another of our clients just asked a similar question.

It would appear the API is either wrong or confusing or both. I think it's right, but confusing, and we have two ways I can think of that we can make it better:

1. When somebody filters to a particular docket, automatically filter the nested attorneys too.

   This is hard because people can do lots of funny docket filters like docket__nature_of_suit=foo. Right now, if that filter were applied to the party endpoint, it would provide all the parties that matched those dockets, and all the attorneys those parties ever had across all dockets. That feels a bit wrong, so it would be better if any docket filters were also applied to the nested attorney objects.

   Of course, if that's hard, most filters are just docket=123, and we could just make that work as a starting point and see if people want more.

   This also breaks backwards compatibility, but perhaps we slip it into v4.

2. The other way to do this would be to allow people to use a second filter to filter the nested attorneys. So instead of doing it automatically, as above, you'd have to add a filter like attorneys__docket__nature_of_suit=foo.

   I like this from a correctness perspective. When you're on the parties endpoint, you get parties returned and your filters apply just to the parties you're querying, not their nested objects. BUT if you want to filter those nested objects you can.

   I don't like this from a practicality standpoint. Usually if you're filtering the parties by docket, you'll want to also filter their nested attorneys, by default. It's kind of annoying to have to take an extra step.

So I think I prefer option 2 because correctness trumps convenience when designing APIs, but I don't know which option is more difficult to build.

One other thing to consider is how this will work when people make OPTIONS requests. Ideally, it'd show up as a filter, but if that's impractical, it'll be in the documentation too.

[mlissner]

This, it turns out, also needs to be done for the attorney endpoint. When you filter it by docket, it has the same problem, because attorneys show their parties, which, again, are not filtered.

See this query for a quick example (but imagine that the parties_represented field has other dockets in it:

https://www.courtlistener.com/api/rest/v3/attorneys/?docket=4214664

We also need to:

• Add party_id and docket_id to the nested parties_represented object.