The challenge
In 2017, Suncorp technical teams were developing a suite of domain and experience APIs as part of their technology strategy. As a large organisation with multiple subdivisions, Suncorp wanted to enable its many departments to effectively collaborate on and communicate about their APIs, including their delivery, uniformity with company standards, and maintenance in order to keep them current.
Alembic was briefed to design and implement a centralised publishing hub that stored the latest version of internal APIs, including documentation and health checks. The hub also ensured APIs conformed to JSON API standards and specific localised constraints, and listed backwards compatibility breakages.
The solution
Timing and scale were two of the largest challenges. Working with Suncorp, Alembic quickly and effectively conducted extensive research within the organisation, including interviews with key stakeholders across all of the IT subdivisions.
Vendor software and services were evaluated, and SwaggerHub was selected as the API platform. Initially manually-updated and maintained by Alembic, the platform was later automated.
The solution was a server component that receives web hooks from the source control system whenever a connected API project pushes new changes. On receiving notification of a change, the system ran a suite of checks against the changed files, and recorded the results in a database. In addition, the server component checked for backwards compatibility changes.
The front end of the API publishing tool is a React application that connects to the server component via a GraphQL API. It lists the APIs in summary form, including problem counts, backwards compatibility status, and details of any issues found. In addition, it provides a place to view up-to-date API documentation, with links back to the source repositories.
Outcomes
Alembic delivered the manually-updated initial version of the API Publishing Tool to realised benefits as it is the go-to authoritative source for the latest API definitions. We also advised on effective ways to leverage the strengths of GraphQL, as well as how GraphQL can co-exist effectively with existing REST APIs, which reduced time to release API changes.
The fully-automated version of the API Publishing Tool was implemented and met the requirements brief.
