In the last quarter of 2024, I decided to take my technical writing skill a step further by learning about API Documentation.

I had little to no knowledge about APIs but was really curious and interested to learn.

While surfing YouTube for API documentation Tutorials, I came across a scheduled video on the Technical Writing Mentorship Program (TWMP) YouTube channel. It was going to be a Q&A session for an upcoming API documentation Bootcamp. My joy knew no bounds! (talk about right timing!). I smashed the notification icon to stay informed. And was live on the call when it was time.

What got my attention on the call was the course curriculum, it was in-depth and well-structured, I just knew I was in the right place.

I got all the information I needed, registered for the bootcamp, and on October 13, 2024, the classes began. A journey that would later open up a whole new world of possibilities for me.

I took this bootcamp alongside JosephBrendan's React Bootcamp and had to juggle both classes.

Getting Started

I started the program not knowing exactly what to expect. Thanks to my amazing program coordinators, there were perks for the top 2 winners of each weekly task just to encourage optimum participation. The prizes were attractive, but I never had my hopes on them. Especially after getting to meet my colleagues who were already big on their game (active developers and cloud engineers)😁. Still, I resolved to stay low-key and give it my best.

The program was structured to last for 3 months, with 6 stages of tasks spanning 2 weeks each.

Stage 1

In the first week, we were tasked with familiarizing ourselves with all things APIs. Our curriculum included resources to guide us, and I also collected several other resources on my Notion board. (In fact, I had a Notion board dedicated to this program—I always do for all of my programs).

I consumed as many resources as I could, learning about types of APIs, Communication methods, Data formats, API testing, and Documentation.

Some of the resources for stage 1 included Introduction to API Documentation and Basics of API documentation using postman both from the TWMP youtube channel.

While on my week 1 learnings, my colleague, Samuel Benson, shared his journey taking the Postman API Fundamentals Student Expert certification. This inspired me to also give it a try.

I registered for the course and got started. It was a well-structured and practical course for anyone who would be learning about Postman and API testing for the first time. This course gave me a clearer understanding of API testing and the Postman API testing tool.

I got my hands dirty testing the Postman Library APIs, and by the end of the program, I had learned so much about Protocols, Request and Response methods, Variables in Postman etc. I was required to complete some tasks on API testing to earn a badge (the process was quite strict but necessary).

After completing all of my tasks, I was awarded the certification Badge. This made me very confident and ready for the next phase of the API documentation journey.

Stage 2

The second stage of the program was focused on learning API documentation best practices and the accompanying resources were Mastering Rest API Documentation for beginners and API documentation course, both from the TWMP community.

Using these resources, I learned best practices for:

Understanding the scope of an API
API Documentation Structure
Documenting Endpoints
HTTP Methods and Usage
PATH and Query Parameters
Authorization Headers
Error and Rate limits etc.

To put this in practice, we were tasked with auditing the Stripe API documentation. It was a thrilling experience for me to get to explore the top finance API docs. With the best practices I had learnt in mind, I audited the Stripe API docs, stating its strengths and weaknesses and proposing recommendations.

*Note: This was the first time I ever got to see a real API documentation.*😁

Stage 3

This would be where we get to put all that we have learned since stage 1 into practice while also learning a new tool.

In this stage, we were tasked with recreating the Twilio Identity and Access Management API docs using Readme. Twilio is a communication API for voice, messages, and emails. Its APIs allow developers to build communication features into their applications.

I was excited for this task because that meant I’d finally be creating my own documentation.

The resource for this task was Document and design API documentation with readme. A resource from the TWMP community.

I learned to test and eventually build my very first documentation on the Readme platform and guess what? After the review for the week, my submission got first place! ( alongside the perks, of course)

This boosted my confidence and got me even more inspired to continue.

Stage 4

For stage 4, we explored Testing and Building API Documentation with Postman - The industry-standard tool for API Testing. And the documentation we explored this time was PLAID - Plaid API allow developers to access financial data from banks, credit card companies, and other financial institutions, and to initiate transactions such as money transfers.

I audited the existing documentation, tested the endpoints to ensure they were all in good state, and built the Plaid API documentation on Postman (unlike Readme, building the documentation on Postman was a lot more demanding - majorly because postman was primarily designed for Testing, not Documentation).

I didn’t get a first or second place this time due to a few mistakes I made, but yeah, I did get an honorable mention😁

My confidence was growing with each tasks, making me feel like this might really be a path for me.☺️

Stage 5 (OpenAPI Specification)

During Stage 5, we got to learn about a very important aspect of API documentation, the OpenAPI specification (OAS).

OAS is a standard for defining and structuring REST APIs. An OAS file allows you to describe your entire API, including:

Available endpoints (/users) and operations on each endpoint (GET /users, POST /users)
Operation parameters Input and output for each operation
Authentication methods
Contact information, license, terms of use, and other information.

API specifications can be written in YAML or JSON. These are programming-language independent, and are readable to both humans and machines. Making it easy for users to understand an API’s purpose and functionality.

Here’s an example of an OAS written in YAML

openapi: 3.0.4
info:
  title: Sample API
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
  version: 0.1.9

servers:
  - url: http://api.example.com/v1
    description: Optional server description, e.g. Main (production) server
  - url: http://staging-api.example.com
    description: Optional server description, e.g. Internal staging server for testing

paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in CommonMark or HTML.
      responses:
        "200": # status code
          description: A JSON array of user names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

And another, written in JSON

{
  "openapi": "3.0.0",
  "info": {
    "title": "My Awesome API",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ],
  "paths": {
    "/users": {
      "get": {
        "summary": "Get all users",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": { "type": "integer" },
                      "name": { "type": "string" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

The complete OpenAPI Specification can be found on GitHub: OpenAPI 3.0 Specification

Why OAS?

OpenAPI allows developers to streamline and improve API design and development processes. Some of its key benefits include:

Better API documentation: Developers can use OpenAPI to provide clear and comprehensive documentation for their APIs. They can use OpenAPI documents to generate interactive API documentation, helping consumers quickly understand how an API works.
Automating processes: OpenAPI has a large development community, with numerous tools available for automating the API design and development process — from generating mock servers and client libraries to automatic API response validation etc.
Improved collaboration: OpenAPI allows parties to come together early in the design process, long before writing any code. The specification serves as a contract that teams can work from, creating an understanding of what the API should do. This contract helps reduce misunderstandings and integration problems.

Stage 6 (Capstone project)

This stage is what we would call in college - the Examination class😅. Here we were required to put all that we had learnt in the program into practice. The task in this stage had 3 major phases:

Phase 1 ⇒ Testing endpoints on Postman

Phase 2 ⇒ Exporting and Editing the OpenAPI Spec file

Phase 3 ⇒ Importing and customizing on Mintlify

The primary task was to revamp The Movie Database (TMDB) API docs using Mintlify and the OpenAPI specification.

TMDB is an open-source movie database that allows developers to access information about movies and TV series.

And Mintlify, just like the 2 previous tools we had used, is an API and product Documentation tool, but allows for more flexibility in customization.

The process

Testing endpoints on Postman

I started by auditing the existing TMDB documentation and taking note of areas of improvement. Then, I verified that all the TMDB endpoints were in good state by testing them on Postman. This took several weeks as the endpoints were quite a lot.

Exporting and Editing the OpenAPI Spec file

Next, I exported my Postman collection into an OpenAPI spec file. This came in JSON format, but because I needed to edit the parameters, I had to convert it to YAML - a more readable syntax and a subset of JSON.

The OpenApi file was quite large, consisting of:

file version
Metadeta
server
tags
paths (representing each endpoint)
security
And up to 18,000 lines of YAML codes.

A good practice would have been to move similar parameters into components, then reference them in their respective paths, but my file size was too large that trying it became a daunting task. I still had to figure how Mintlify would work and the deadline for the task was getting closer, so I had to move to the next phase.

Customizing on Mintlify

Mintlify is an industry-standard tool for creating custom documentation and API references. Compared to other tools I had used earlier, Mintlify had a much difficult learning curve. I had to look it up everyday, spend some time trying to understand its documentation, or watch some videos, then close the project again to try the next day. TBH, I almost gave up on it cos it was becoming frustrating…lol.

Then one day, I said to myself that I had come too far in this journey to give up, I knew if I give it more time and undistracted attention, I would get it done.

I decided to be more intentional with learning Mintlify, I spent at least 2hrs on it a day, went through the documentation with keen attention this time from the top, implementing every step. And on that first day, I had gotten the TMDB brand color and logo set. It was all beginning to come together, and that inspired me to keep going. I tried it again the next day, and the next and the next.

I looked up other documentation to get inspiration, but they all seemed to look the same, some with long, cluttered, and boring texts. But the designer in me would not settle (lol)…I thought I could make mine a little more interesting because why not? Even developers would appreciate a good user experience.😃 I decided to utilize all the customization components Mintlify provided, threw in a little bit of my CSS skills, and trust me, I was thrilled with the outcome and even more proud that I could pull that.

I reminisced on the entire journey several days before submission, and couldn’t just deny the growth. I had come a long way!

I showed my project to my APs and developer friends and they were all wowed. I thought my mentors would be impressed too.

The entire capstone project duration lasted for 2 months. Few weeks after submission, we had a call to know our final fate, and lo and behold, my capstone project got first place! alongside my amiable colleague and friend, Rilwan Edun whose project emerged 2nd place!

To crown it all, I was also certified as an API Documentation Writer!🤭

Even though I knew I still had so much to learn regarding this journey, this meant so much to me because, it made me truly believe I was good at something people could testify to, it made me realize that going out of your way to do the little things really do payoff, and I can’t even begin to mention the opportunities this has opened up for me. An opportunity to work closely with my Chief Mentor (which has always been my dream), to join the TWMP community as a mentor, and even recommended to be mentored by Robert Delwood, a Lead API Documentation Writer with over 20years of experience (this indeed had to be the highlight for me)!☺️

My Key Takeaway!

This Bootcamp has taught me that learning is immersive ( You learn to do by doing). I had started the bootcamp knowing barely anything about API documentation. But by immersing myself with the resources provided, and utilizing mentorship and collaboration, I was able to gain industry-level experiences with 3 solid projects in my portfolio in a short time.

Just like you would learn a new language faster by surrounding yourself with the people who actually speak it and also getting to speak it yourself, you can learn anything faster by actually getting to do it. I found the approach in this bootcamp to be the best, which can be applied to learning just anything. And moving forward I’ll be applying it to all of my learnings.

If you want to learn how to write, just start writing. Want to learn how to design, immerse yourself in it already, you will fill in all the lapses as you go, and you will grow even faster that way.

Being a self-learner could be a good idea, but nothing beats learning with like-minded and even more experienced people.
Access to resources: I wouldn’t have had access to the industry-standard resources I used if I had to learn it all by myself.
Accountability: I may not have had the structured learning experience or the discipline to see it to the end if I had to learn alone. Who would I be accountable to, for deadlines, or how would I have even known if I did the right thing or not?
Collaboration: I wouldn’t trade the shared knowledge and perspectives for anything. Who knows, maybe I would be thinking the way I knew it was the only way to do it.

In all of these, my key takeaway would be, if by any means you have the chance to learn with a mentor, or register for a Bootcamp to learn anything, please do, you’ll get more advantage than if you had to learn it on your own.

Moving forward

This learning experience has transformed my skills and mindset, and moving forward, I look to continue my learning around API documentation, API design, and all things API. I feel like I have found a new love, and all I want to do is immerse myself in it. I’ll be exploring this path with my already existing passion for Blockchain Technology and User Experience design. I hope to be a voice in the API documentation field, to change the narrative of Documentation as an afterthought instead of a necessity in the software development lifecycle. And to make the knowledge of API Documentation accessible to anyone who might be curious to learn about it.

I really did enjoy sharing this journey. I hope you find it insightful and enjoy reading it as much as I enjoyed sharing it with you If there’s anything else you’d like to know or have something you’d like to share, please do not hesitate to share them in the comment section, I’ll be more than excited to hear your thoughts on this topic or anything else.