Case Study: GitHub
Now that you have seen some of the guidelines proposed in this book. It is now time to observe how these guidelines have been implemented and followed in the real world. What better organization to observe over the years than every developer's favorite website, GitHub. Both the documentation and the company have gone through enormous amounts of changes in the last decade.
The GitHub documentation website went from this funky looking thing...
To this somewhat less funky looking thing...
To now to this. Yay! Much better don't you think?
Fun fact: V1 and V2 were both deprecated on March 28, 2012. V3 has been in effect ever since.
In this section, we'll be exploring 3 key changes that GitHub has made since versions 1 and 2 all the way till now in V3, and how they were able to better their APIs by applying some of the guidelines written in this book.
Application-Specific Media Type
Before
If you dig around the old GitHub documentation, you will see that GitHub did not support any custom vendor media types in their API. They did however, support XML and JSON from their responses. This was quite primitive, but it did work.
After
Nowadays, GitHub's public API is quite popular and is used by the masses. GitHub has added their own custom media type as application/vnd.github.v3+json.
Not only that, GitHub has also dropped support for XML in favor of JSON.
URI Actions
Before
Back in the day, GitHub would create their endpoints with an entity type like http://github.com/api/commits or http://github.com/api/repos, but would make the mistake of tacking on an extra verb like list, show, or even create in order to describe what action those endpoints were trying to perform.
Here are some examples of what GitHub did back in V2 of their commit endpoints.
If you recall guideline #4 of the URI path design section of the book: "Avoid Actions/Verbs in the URI".
Do not use actions and/or verbs to describe the URIs, that's what the HTTP method verbs are for. Only create functional endpoints, meaning URIs with actions/verbs if you have to, try to avoid it as much as possible.
After
In V3 of the GitHub API, they followed the guideline for their commit API, and have since removed their action-oriented verbs in the URI and relied more on the implicitness of their HTTP verbs themselves.
Notice the lack of action verbs in the URI in the commit comment. project, and organization endpoints, and the proper usage of the GET, POST, and PATCH verbs.
Pluralization of Nouns in the URI
Before
Before the release of V2 and V3, GitHub had a very inconsistent naming scheme, mixing in both namespaces like user vs users or project vs projects in their URIs. Although this might have been just a semantic issue, and not really a big deal, one can potentially see the issue when a person gets api/user confused with an endpoint for getting the current auth user or vs getting a list of users.
Recall guideline #1 from the URI path design section: "Resource paths should be Plural".
Resources should be nouns and pluralized. This is very important as the other guidelines build on top of this concept.
After
Perhaps I am nitpicking here, but it seems like GitHub did indeed change every single one of their endpoints in V3 to pluralized nouns. The most evident being the user in V2 vs users in V3 shown above and below.
Last updated
