Skip to content

Instantly share code, notes, and snippets.

@technoweenie

technoweenie/gist:5101109

Last active January 7, 2016 16:56
Show Gist options
  • Star 3 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save technoweenie/5101109 to your computer and use it in GitHub Desktop.
Save technoweenie/5101109 to your computer and use it in GitHub Desktop.
Download ZIP
API Existential Crisis
Raw
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?

@metavida
Copy link

metavida commented Mar 7, 2013

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

@technoweenie
Copy link
Author

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment