API Existential Crisis

gistfile1.md

API Existential Crisis

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"?

1. 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.
2. 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?

As a developer, I like:

GET /u/123
GET /r/123

But the GitHub Voice™ favors spelling everything out. Maybe URLs aren't part of The Voice?

Would we favor username and nwo-based paths for all endpoints or just for a single templatized GET and from there you'd need to use the IDs?

My thinking is we'd favor the shorter ID based paths. The longer paths are just nicer for humans.

Also: API v5 would be a good chance to revert back to longer URLs and IDs :)

It doesn't seem like there'd be any sensible way to create a user or repository URL with an ID from scratch. Wouldn't it always have to be returned from a previous API call? If that's the case, the naming of the ID endpoint seems like it'd be mostly for debugging/sniffing, and an easy way to remember it is less important.

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.)

We had a few things planned to "finish" API v3, but at this point we're just going to call that API v4.

I'd go with "user" over "user_id", as it fits our API conventions better. But the singular "user" resource name bugs me:

GET /repositories/123/issues
GET /user/123/emails

How about just adding a couple of extra "search by id" resources? Something like this:

> GET /users?id=123
< 303 See Other
< Location: /users/technoweenie

Then there would be no need to change/rename existing resources.

@timcraft: Thought about that. It would still be disruptive to API clients. Also, could cause problems if someone else renames their user to replace the first renamed user. Going with IDs from the start makes the flow much easier for API clients.

I tend to agree with @sigmavirus24 that being explicit is nice. I'll throw a few non-standard options on the table

GET /users/by_id/123
GET /users/id=123/emails

Thanks for the feedback, everyone. We're going with these new paths:

• /user/:id
• /repositories/:id
• /organizations/:id

We'll be transparently rewriting (no HTTP redirects) the current paths until API v3 goes out of style. You may see them in various hypermedia links though.