Keep API Prototypes Up to Date in Your Developer Portal Using WireMock and Atlassian Compass

In this blog, we'll explore how to keep your developer portal up-to-date with the latest version of the APIs being developed in your organization. We’ll use WireMock Cloud and GitHub to achieve this, with Atlassian Compass acting as our example developer portal. This Git-based integration allows teams to build APIs based on a working mock prototype while keeping their developer portal in sync with the latest changes, ensuring every developer has access to the latest prototype – improving collaboration and accelerating API development.

The Challenge: Keeping API Work in Sync Across the Organization Using a Developer Portal

Developer portals serve as a central hub for developer documentation, specifications, and testing interfaces. Our goal is to keep the APIs that are currently in development up to date in the portal. This means automatically synchronizing the latest changes from API prototypes and mocks to the developer portal - so that if a team developing an API makes a change, downstream developers always have access to the latest API designs and specifications. This will prevent costly miscommunication between API consumer and producer teams.

By keeping both mock and production APIs up-to-date in the portal, teams can:

• Improve discoverability of APIs
• Facilitate better collaboration between API producers and consumers
• Enable faster integration and testing of new API features
• Maintain a single source of truth for API documentation
• Streamline the transition from prototyping to production

Since many teams use WireMock Cloud to design and prototype APIs, we want to make sure that the developer portal reflects the latest changes made in WireMock. We also want to make it easy to test the different API endpoints and understand which types  of responses they return, while minimizing the need to context switch and leave the developer portal.

The Solution: Updating API Specs Automatically via WireMock Cloud’s Git Integration

For the sake of this example, we’ll be building our automated workflow around Compass - Atlassian’s developer portal offering. Compass helps teams track and manage the components they build, complementing tools like Jira which focus on tracking the effort involved in building those components. This same solution could work with a variety of other dev portals and any tool that can sync with GitHub, BitBucket, or GitLab.

We’ll also be using two key features of WireMock Cloud:

• API Prototyping: WireMock Cloud enables rapid and collaborative API prototyping. Developers can quickly create mock endpoints based on an OpenAPI spec. As you define stubs and responses, WireMock automatically generates and updates the corresponding spec, providing a real-time, accurate representation of your API design, and allowing for more realistic integration testing against the mock API.
• Git integration: WireMock Cloud supports bidirectional Git synchronization for your mock’s OpenAPI specs. This feature allows you to push updates from WireMocks Cloud to your Git repository and pull changes from Git into WireMock Cloud, and keep your API definitions in sync across different tools and environments.

In just a few simple steps, we can build out the following workflow:

‍

1. Connect WireMock Cloud to a Git repository (via GitHub, GitLab, Bitbucket). Changes made to the API in WireMock Cloud trigger updates to the OpenAPI specification, which is then automatically pushed to the Git repository.
2. A GitHub Actions workflow (or similar CI/CD pipeline) is set up to monitor changes in the Git repository. When changes are detected, the workflow publishes the updated OpenAPI specification to Atlassian Compass.
3. Compass then updates its component catalog, reflecting the latest API changes in the developer portal. This allows any developer with access to the portal to see the most current version of the API.
4. Developers can send API calls directly through Compass to see how the mock behaves in different scenarios, making full use of advanced WireMock functionality such as stateful mocking, scenarios, chaos engineering, and more.

This implementation ensures that any modifications made in the prototyping layer are automatically propagated to Compass, keeping your developer portal consistently up-to-date (which helps keep everyone on the same page). As an added benefit, you get a full-featured mocking platform embedded directly into your dev portal! 

‍Step by Step Implementation Tutorial

Let's walk through an example of how this automation works in practice:

We start with a mock API in WireMock Cloud:

For this example, we’ve created a simple payments API with various endpoints - charges, customers, etc. WireMock Cloud will automatically generate an OpenAPI spec from this mock:

If we add a new endpoint such as a method to GET invoices, this will automatically be updated in the spec:

Since we’ve enabled Git integration - in this case with GitHub - םnce we update the new method, the updated spec is pushed to our GitHub repository:

Within the same repository, we can use GitHub Actions workflows to push the updated spec directly into Compass. Once we do that, we can now see our API prototype in Compass:

We can then go ahead and test our mock API by actually sending an API call. On the most basic level, this allows different developers to see what kind of response the API will return, and develop around it. Using WireMock Cloud, you can also define advanced behaviors and functionality such as delays, specific error codes, dynamic responses, and more. You basically have an embedded ‘API playground’ to work with in order to see how the API works in various application scenarios.

And there you have it - as long as we keep the GitHub repo in sync with the changes we make to our mock / prototype API, any change we make will be reflected in our developer portal. This ensures that everyone is working on the most up to date version and streamlines the process of developing, testing, and iterating on our API.

>> Build your own API mocks with WireMock Cloud

‍