WireMock’s Dirty Secret: Ignoring API Specs & Letting Invalid Examples Slip Through 

Overcoming the Challenges of Hand-Rolled Mocks with Contract-Driven Development 

APIs and microservices have transformed the way software systems are built and maintained. However, developing a system that relies on multiple services—both internal and external—presents unique challenges, especially when some services are not fully available. In this critique of WireMock, we examine the critical importance of service mocking, the drawbacks of traditional hand-rolled mocks, and how adopting contract-driven development with API specifications can mitigate common pitfalls. 

The Importance of Service Mocking 

One of the crucial aspects of modern software development is overcoming dependencies on external and backend services. Imagine you are building an application with several dependencies that are still under construction or intermittently available. The prevailing practice to navigate this obstacle is to create service mocks. These mocks simulate the behaviors of the actual services, allowing for continuous development and testing. 

Quick Setup vs. Long-Term Pitfalls 

While it’s relatively quick and easy to create hand-rolled mocks based on agreed request-response patterns with other teams, this method has severe drawbacks. As highlighted in our podcast episode, such mocks can quickly fall out of sync with the actual service as it evolves (e.g., upgrading to a new version). This discrepancy can lead to significant issues during integration testing, sparking rework cycles and delaying deployment. 

The Role of API Specifications 

To counteract these challenges, basing service mocks on API specifications such as OpenAPI or Swagger can make a substantial difference. These specifications serve as a contract between the service provider and consumer, detailing the expected request and response formats. When used correctly, they facilitate service virtualization based on these well-defined contracts. 

Real-World Example 

Consider an OpenAPI specification that defines a getProducts operation. This operation returns a list of products, where each product adheres to a specific schema. In our example, we’ve used WireMock to set up a service mock adhering to this specification. However, WireMock has some significant limitations, primarily in the realm of example validation. 

The Dirty Secrets of WireMock 

WireMock is a popular tool for creating service mocks, but it has its set of pitfalls such as allowing you to set up responses that do not conform to the specified schema without providing any form of validation feedback. 

No Feedback on Schema Violations 

For example, if the API specification indicates that the price field should be a number (specifically a float), WireMock will still allow you to set this field as a string without any feedback. This can lead to incorrect mock responses, and any API consumer depending on this information will run into errors. Essentially, you are back to square one with a mock that is not representative of the actual service. 

Lack of Developer Workflow Guarantees 

Another significant issue is that WireMock does not guarantee that the API specification used in its setup is the same one implemented by the API provider. If the provider updates the API specification without informing the consumers, the mock remains outdated. The only point where this mismatch becomes apparent is during integration testing, but by then, the purpose of service mocking has already been defeated. 

Embracing Contract-Driven Development 

To overcome these limitations, adopting contract-driven development practices can be transformative. By leveraging API specifications as executable contracts and maintaining them in a central Git repository, all teams—both providers and consumers—can ensure they are working with the correct version of the specification. 

Benefits of Centralized Specifications 

Centralizing the API specification offers multiple benefits: 

1. Consistency: 

Ensures all mock services are consistent with the actual API. 

2. Real-time Updates: 

Any changes in the API specification are immediately available to all teams. 

3. Validation: 

Tools can be put in place to automatically validate that any mock conforms to the latest API specification. And example validation against API specification is crucial such as the capabilities provided by Specmatic Smart Service Virtualization. 

Conclusion 

As microservices and APIs continue to dominate the software development landscape, the importance of robust, reliable service mocking cannot be overstated. Hand-rolled mocks can provide a quick fix but are fraught with long-term pitfalls. Leveraging API specifications for service virtualization addresses these issues, ensuring consistency and reliability. Tools like WireMock have their uses but fall short in critical areas like example validation and adherence to specifications. By embracing contract-driven development and maintaining centralized API specifications, teams can avoid the pitfalls of traditional mocks and fully realize the benefits of microservices. 

Whether you are a seasoned developer or just getting started with microservices, understanding the nuances of service mocking and API specifications can set your project up for success. 

See also: Comparison: Specmatic vs WireMock