How I Use Github’s Wiki Feature For API Documentation
As part of my goal to practice working with a team, I recently started working on a project with a fellow alum from my cohort. I agreed to create the API for the app by using Rails. Prior to working with others, I didn’t have much experience documenting my work. This is mainly because all of my past work was personal projects that didn’t I intend on working on extensively in the future. However, working with a team changes this. I needed a way to document my REST API so that my teammate would be able to work on the front-end and properly utilize the API without any confusion. After some research, I decided to use Github’s Wiki feature. Here’s how I used it.
The first step was to navigate to the Wiki tab in my Github project and click on the ‘Create the first page’ button. After clicking it you’re prompted to create a new page. I used the first page to create an introduction to my API, as well as include details about how authentication works.
After studying the documentation of several REST APIs, I noticed a pattern between all of them. I took inspiration from Twitch’s API reference and added modifications that I thought would work better for my project.
Here’s an example of one of the actions that I documented:
Let’s break it down!
Action Name/Details
In this case, the action name of the action I’m documenting is ‘Create Board’. Under that is a simple description of the action. This is the perfect place to include a small summary of the action you’re documenting.
Authentication
In my case, my authentication system is relatively self-explanatory and straightforward, so I didn’t include much information here. I also had authentication information on the front page, so I feel that re-writing it here was kind of redundant. Linking it to the resource is the best option in my case, but if there is an action that requires specific authentication information, here’s the place to put it.
URL
Included in the URL information are the method and the path. This is pretty straightforward.
Request Data
If the action requires any kind of request data to be sent, here is where information on request data would be documented. The parameter name, data type, description, and whether or not the parameter needs to be sent is what I figured would be important to be documented.
Example Request
This is ultimately the most optional and custom part of my documentation. For this project, I knew that the language that would be interfacing with this API the most would be JavaScript. Because of this, I decided to include an example request written in JavaScript. It’s not necessary what-so-ever, but I figured it would nice to include for when the front-end is developed.
Response Paramters
Similar to request parameters, response parameters include the parameter name, data type, and description. This helps give a general idea of what kind of data should be expected in the response.
Example Response
This is just another way to see what kind of data is being returned. In this case, the response is sent in JSON.
And that’s it! It should be noted that under certain circumstances parts of the documentation are unnecessary. For example, if an action’s method is a GET request, including information on the request data is unnecessary. Overall, this is just an example of how I created documentation based on my API. Every project is different, and information should be added and removed accordingly. Again, I am very much a beginner when it comes to documenting APIs, so if there is anything that I did wrong or could have done better, please feel free to let me know!
Edit: Here is the link to the wiki referenced: https://github.com/smcbride1/collaborative-workspace-backend/wiki/Boards
