One bit of feedback we've heard from some heavy users of the API is that they want to access user and repository data by ID, and not name.
GET /users/technoweenie
GET /repos/technoweenie/faraday
If you're tracking user or repository data, using a URL with a unique and unchanging ID means the application won't break if the user or repository is renamed.
If we did this, it would be done in a careful matter with a new media type for API v4.
GET /users/123
GET /repos/123
However, we understand that API developers may be caching the old API v3 URLs in their applications. How will they resolve "/users/technoweenie"?
- Access "/users/technoweenie" using the API v3 media type, get the new URL in the "url" property, and start using that. I don't like this, because now we have to worry about what media type a URL is associated with.
- Accept "/users/technoweenie" in API v4 and redirect to the new endpoint. This is a favorable solution except...
For whatever reason, GitHub allows users with integer names. So, we'd want to change the endpoint instead. It's easy for "repos", since it is an abbreviation:
GET /repositories/123
What about users?
One idea is using shortcut paths:
GET /u/123
GET /r/123
API Clients can use that. If possible, the API would still respond to the longer paths too:
GET /u/123/emails
GET /users/technoweenie/emails
The GitHub API Team would love to hear how this would affect you. Would shortening the paths to "/u/" or "/r/" cause any problems or hurt feelings? Any suggestions for an alternate "users" path to support IDs?
I would think that the difference between
/u/
and/users/
might be lost on some, and coming from python ("Explicit is better than implicity"), perhaps/user_id/
might be a better endpoint? I do not see how shortening those paths could cause hurt feelings though. Also, since this is for v4 I don't see it causing any immediate problems for most users. (I'm really only guessing since v3 still isn't final.)As for people caching the v3 URLs, most (if not all of them) should be using a media type which would make it easier to distinguish their intention, i.e., if someone sends a v3 media type they're expecting v3 behaviour. If someone sends a v4 media type but sends a v3 URL, they should be redirected to the new endpoint.
(Side note: As a wrapper author, I don't see implementing this being difficult at all, so I'm certainly +1 on this.)