In my opinion, one of the hallmarks of a good API is that it is self-consistent. It establishes easy-to-remember conventions and then follows them.

As I'm trying to adopt the 2.0 API, I'm finding a whole bunch of inconsistencies in the API that are making it really frustrating to work with. Here are some of the things that are really bothering me:

• The value for the sort query parameter should always correspond to a field in the object of the returned JSON. It usually doesn't. For example, if I want to sort badges by their badge_type, I have to pass in sort=type. It should be sort=badge_type. (another example, for tags I do sort=popular even though it really should be sort=count)

• I should not be able to sort by something that does not correspond to a field in the object returned. For example, I can sort Tags by "activity" (sort=activity), but there's nothing in the returned Tag objects that indicates what that activity is. If we really want to be able to sort Tags by the time they were last used, then Tags should have a last_used_date field that contains the timestamp of the last time the tag was added to a Question, and then I should do sort=last_used_date)

• I find it really annoying that some object fields don't make sense in all contexts. For example, the Badge user field is only relevant if I'm requesting awarded badges (i.e. via /badges/recipients or /badges/{ids}/recipients). If the field is not always relevant, it should not be there. Instead, the */recipients endpoints should return "Awarded Badge" objects that have award_count, user, and badge fields.

• Tags, Badges, and Users all have name (or display_name) fields. So why can't I do inname=foo when requesting Badges? If you're going to offer searching by name on some things, you should offer searching by name on all things.

There are more, but these are ones that I remember right now. As I come across more I'll also post those.