Back story

Affinity Employer Services is my main employer. We specialise in providing payroll software and services for the Australian and New Zealand markets. Although we have provided a customer web API for several years, in 2024 we decided to build a new one from scratch.

Design and documentation

This time we wanted to standardise our available resources and the subsequent naming of those resources. We decided to provide a range of resources that appeal to current and prospective customers, making it easier to get, add, update and delete relevant employee and transactional information. We also wanted to standardise JSON field names, making them instantly meaningful to those consuming our API.

Our company owner Bruce (who is also Head of Technology and my direct manager 😬) specifically asked that documentation be provided in the ‘Swagger’ format so it could be easily shared and maintained, as well as provide code samples and the ability to do test calls to the API.

Myself and senior developer James teamed up to produce the docs based on the new standardised resources. James produced an outline in YAML and I polished things up, adding descriptions, tags and fleshing out the info object. Conceptual docs (intros, getting started, authentication etc.) are planned, and we will continue to round out descriptions of parameters and other attributes.

We have chosen Redoc, Redocly’s free open-source product, to publish the docs. Obviously, Redoc is very dear to my heart, having done some freelancing work for Redocly in 2022/23.

View the docs

The published output can be viewed here. Customers have been impressed so far, and I look forward to enhancing the docs as more objects are added.

Go Home