API Inconsistencies

In my opinion, 1 of nan hallmarks of a bully API is that it is self-consistent. It establishes easy-to-remember conventions and past follows them.

As I'm trying to adopt nan 2.0 API, I'm uncovering a full bunch of inconsistencies successful nan API that are making it really frustrating to activity with. Here are immoderate of nan things that are really bothering me:

• The worth for nan benignant query parameter should always correspond to a section successful nan entity of nan returned JSON. It usually doesn't. For example, if I want to benignant badges by their badge_type, I person to walk successful sort=type. It should beryllium sort=badge_type. (another example, for tags I do sort=popular moreover though it really should beryllium sort=count)

• I should not beryllium capable to benignant by thing that does not correspond to a section successful nan entity returned. For example, I tin benignant Tags by "activity" (sort=activity), but there's thing successful nan returned Tag objects that indicates what that activity is. If we really want to beryllium capable to benignant Tags by nan clip they were past used, past Tags should person a last_used_date section that contains nan timestamp of nan past clip nan tag was added to a Question, and past I should do sort=last_used_date)

• I find it really annoying that immoderate entity fields don't make consciousness successful each contexts. For example, nan Badge personification section is only applicable if I'm requesting awarded badges (i.e. via /badges/recipients aliases /badges/{ids}/recipients). If nan section is not ever relevant, it should not beryllium there. Instead, nan */recipients endpoints should return "Awarded Badge" objects that person award_count, user, and badge fields.

• Tags, Badges, and Users each person sanction (or display_name) fields. So why can't I do inname=foo erstwhile requesting Badges? If you're going to connection searching by sanction connected immoderate things, you should connection searching by sanction connected all things.

There are more, but these are ones that I retrieve correct now. As I travel crossed much I'll besides station those.