Back story

In April 2021 I found Nextory’s job posting on Upwork. Nextory is an audio and e-book streaming service based in Sweden. They were looking for a tech writer to transform their REST API docs published on a Confluence page into a tight suite of docs centred around the OpenAPI Specification (OAS). Attached to the job posting was a MS Word doc containing a dump of the Confluence page.

I downloaded the MS Word doc, did some research on Nextory (thanks Google Translate!) and made a start. I documented several endpoints, then contacted Nextory’s head of engineering to introduce myself and show him what I’d done. Luckily for me, I was invited to continue documenting the API and use the experience as practice. Although I didn’t want to be compensated, I was paid a small fee for my efforts. This project was my first real-world experience documenting a REST API.

Tools and approach

I used the excellent Stoplight Studio to write the definition (aka reference) doc as well as the supporting (overview) doc. I used both the UI and worked within the raw YAML so I didn’t rely wholly on the UI. I find Stoplight’s linter to be a little too sensitive so I used Swagger UI to validate the YAML from time to time when I thought the validation errors were getting a little over the top in Stoplight. I set up an integration with my Nextory repo in GitHub to store yaml and md files.

Other tools used: Freeformatter and JSON Schema Validator (to check the occasional incorrect JSON from the source MS Word doc) and Tables Generator (to build markdown tables fast).

As Nextory uses their API internally to communicate with the app backend, I kept the supporting doc to a minimum and didn’t get a chance to write the information an external audience consuming the API would typically get. Despite this, I was still able to document a lot of useful supporting information for the Nextory devs. This will allow new starters to get familiar with the API, and provide a reference for existing devs. It can also be used to do some retrospective tidy up in the API itself.

Project stats

The project began in April 2021 and finished in August 2021. About 110 hours of tech writer effort went into the project. The final reference doc ended up at 10591 lines of YAML. There were 53 endpoints, a mixture of POST and GET. I did a handover to the head of engineering at Nextory at the end of the project. This involved advice on platforms for maintaining and testing the docs (Stoplight, Postman, Swagger), opportunities for removing duplication and utilising the reusable components feature of the OAS, and ideas about consistency of naming elements going forward.

View the docs

Click here to view my GitHub repo which contains a cut-down version of the definition (.yaml) and the supporting doc (.md). I cannot show the entire definition or supporting doc due to confidentiality. In the cut-down, only a small number of GET operations are shown but will hopefully give you an idea of what I did.

The full reference doc and the conceptual doc can be viewed on request if you’re interested in hiring me.