This event was 1 week and 5 days ago, I'm late to the review party, I know. BUT, it would pain me not to write about my time during this event and share some of the things I learned

I'm writing this 1 week and 5 days after the event to write this. Why? It's cause I'm late and other activities just took priority, but I'm happy I wrote this eventually. One thing I would say about the event though, it was super cool. I loved connecting with new developers as well as people I knew before in this space.

In this article, I'm going to share what I learned during the course of this event and my experience overall.

Now, it's time to speak about the meat of the matter.

Technical Writing Talk

I missed some talks cause I came early of course (African time), but one talk I didn't miss that was momentous for technical writing was Funke's talk on "From Design to Documentation: Building Interactive OpenAPI Specification" so I'll be sharing a bit of what I learned during the talk and hopefully, you also learn a thing or two from my experience.

She spoke well on the topic and by the end of the talk, I was informed on the building blocks of OpenAPI specification and some tools that would come in handy in my technical writing journey. Well, on the API documentation side at least.

Although, as I write this, my memory about the talk is pretty fuzzy so I'm combining the information I got from the talk with my knowledge and research to present you a well-made flavourful soup of OpenAPI documentation concepts wrapped with the delicious covering of YAML code.

Building Blocks of OpenAPI Specification

The OpenAPI Specification (OAS) is a community-driven open standard within the OpenAPI Initiative, a Linux Foundation Collaborative Project. It defines a format for describing HTTP-based APIs, enabling developers and stakeholders to understand a software's capabilities without needing access to its source code or additional documentation.

In essence, the OpenAPI Specification provides a structured and standardized way to document how APIs work, including details about available endpoints, request and response formats, authentication methods, and other relevant information.

OpenAPI's building blocks consist of different objects that help make it great. These objects are:

1. OpenAPI Object

   The root object of the OpenAPI document. It includes metadata about the version of the OpenAPI Specification being used e.g

    openapi: 3.0.0
    ...
   

2. Info Objects

   The root object of the OpenAPI document. It includes metadata about the API, such as the API version, title, description, and the version of the OpenAPI Specification being used

    info:
      title: Todo List API
      description: A simple API to manage a todo list
      version: 1.0.0
    ...
   

3. Servers Object

   Specifies the base URLs for the API. Multiple servers can be defined as production and staging environments.

    servers:
      - url: https://api.example.com/v1
        description: Production server
      - url: https://staging-api.example.com/v1
        description: Staging server
    ...
   

4. Paths Object

   Describes the available paths and operations for the API. Each path corresponds to an endpoint and contains methods (such as GET, POST, PUT, DELETE) and the operations available at those paths.

    paths:
      /tasks:
        get:
          summary: Get all tasks
          tags: [Tasks]
          responses:
            '200':
              description: A list of tasks
              content:
                application/json:
                  schema:
                    type: array
                    items:
                      $ref: '#/components/schemas/Task'
        post:
          summary: Add a new task
          tags: [Tasks]
          requestBody:
            required: true
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/NewTask'
          responses:
            '201':
              description: Task created successfully
              content:
                application/json:
                  schema:
                    $ref: '#/components/schemas/Task'
      /tasks/{taskId}:
        get:
          summary: Get a task by ID
          tags: [Tasks]
          parameters:
            - name: taskId
              in: path
              required: true
              schema:
                type: string
          responses:
            '200':
              description: A single task
              content:
                application/json:
                  schema:
                    $ref: '#/components/schemas/Task'
            '404':
              description: Task not found
        put:
          summary: Update a task by ID
          tags: [Tasks]
          parameters:
            - name: taskId
              in: path
              required: true
              schema:
                type: string
          requestBody:
            required: true
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/NewTask'
          responses:
            '200':
              description: Task updated successfully
              content:
                application/json:
                  schema:
                    $ref: '#/components/schemas/Task'
        delete:
          summary: Delete a task by ID
          tags: [Tasks]
          parameters:
            - name: taskId
              in: path
              required: true
              schema:
                type: string
          responses:
            '204':
              description: Task deleted successfully
    ...
   

5. Operation Object

   Defines a single API operation on a path, including its parameters, request body, responses, security requirements, and more.

get:
      summary: Get a task by ID
      tags: [Tasks]
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A single task
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '404':
          description: Task not found
    put:
      summary: Update a task by ID
      tags: [Tasks]
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewTask'
      responses:
        '200':
          description: Task updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
...

6. Parameters Object

   Defined in the operations or path, this object specifies the input parameters for an operation, such as path parameters, query parameters, headers, and cookies. Each parameter includes details like name, location (in), description, required status, and schema.

    get:
          summary: Get a task by ID
          tags: [Tasks]
   
          #parameters here
          parameters:
            - name: taskId
              in: path
              required: true
              schema:
                type: string
    ...
   

7. Request Body Object

   Describes the request payload, including the media types (e.g JSON, XML, form data, plain text, and more) supported and the schema for the request body or as OpenAPI describes it. It is the request body that usually contains the representation of the resource to be created.

put:
      summary: Update a task by ID
      tags: [Tasks]
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string

      # request body example here
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewTask'
     ...

Finally, it all comes together as a great API documentation example:

openapi: 3.0.0
info:
  title: Todo List API
  description: A simple API to manage a todo list
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
    description: Production server
  - url: https://staging-api.example.com/v1
    description: Staging server
paths:
  /tasks:
    get:
      summary: Get all tasks
      tags: [Tasks]
      responses:
        '200':
          description: A list of tasks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Task'
    post:
      summary: Add a new task
      tags: [Tasks]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewTask'
      responses:
        '201':
          description: Task created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
  /tasks/{taskId}:
    get:
      summary: Get a task by ID
      tags: [Tasks]
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A single task
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '404':
          description: Task not found
    put:
      summary: Update a task by ID
      tags: [Tasks]
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewTask'
      responses:
        '200':
          description: Task updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
    delete:
      summary: Delete a task by ID
      tags: [Tasks]
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Task deleted successfully

components:
  schemas:
    Task:
      type: object
      properties:
        id:
          type: string
          example: "1"
        title:
          type: string
          example: "Freshen up - 10:00am"
        completed:
          type: boolean
          example: true
    NewTask:
      type: object
      properties:
        title:
          type: string
          example: "Attend API Conference Lagos - 11:00am"
        completed:
          type: boolean
          example: true

I want to go so deep and discuss all you can know about the building blocks from the simple ones to the advanced concepts, but I have decided to do that in a later article and just keep my focus on the event now. I mean, you've got to follow me so you don't miss out on any updates...I mean, why not? 😉

The next part of the talk I remember was Stoplight and we are going to look briefly at it below.

Stoplight? What's that??

Design first. Develop better. Stoplight is a collaborative API design platform that enables you to build excellent APIs and create scalable API programs that fuel innovation.

That's an extract from their about us page on their website which explains what they are about, but I'd like to still break it down so we can understand better.

Let's think of it this way. Let's say, you're trying to cut a potato

In order to fry the potato to make it edible, you would need to cut it. The potato can be cut in two ways:

1. Using a knife

2. Using a machine

One way is slower than the other, but over time if you're used to handling it with a knife, you obviously have more flexibility and control over how you want your potato to look, but if you're using a machine, it's faster and would cut it out in a nice and consistent shape.

The machine in this context is Stoplight. And the knife is the traditional Swagger way of writing OADs. I CANNOT give a full opinion yet on the product till I investigate and research further on what I gain from using it, what I lose from using it, and so on.

So again, till further notice. Maybe, you can follow me and comment down below if you want to see that article come to fruition (shamelessly plugging my blog again).

Funke spoke in detail about this and even showed an example of how this works which was great! Unfortunately, we couldn't go so deep into it because of time.

Final Thoughts

Aside from the talks, there were a bunch of merch from companies like Postman, Fincra, and other tech companies present. Plus, there was food! 😭 Good food!

All for the price of FREE.

I won't lie, this honestly felt like a paid event given to all for the price of attendance, and I won't mind paying a small fee for the next one because of the value the organizers, speakers and this whole event provided was immense and I just feel bad not offering them something in return. Aside from paying, I think I'll help out at the next API conference one way or another. I hopefully would like to talk or share any ideas I'd like them to improve on.

Pictures with Some Friendsss

Shoutout to Kruse for introducing me to some key frontend people running the Vue.js community, I wouldn't have even known they existed if not for him.

Well, that was my experience so far during API Conference 2024. Did you also attend? Perhaps you had a different experience or you just happened to come across my blog from nowhere. Let me know in the comments below what you think!

Thank you for your time reading this, and I hope to see you again in the next article. <3

Follow ME!

You haven't followed me? You're dulling! Follow me so as not to miss out on any article updates whatsoever or for more content. :)

• Twitter: @the_jonin

• LinkedIn: linkedin.com/in/olasunkanmi-fafowora