Build Apps from API specs using AI: Self-Correcting Contract-Driven Agentic Workflows with Specmatic

Harnessing the Power of API Specifications for Robust Microservices 

Modern microservice architecture hinges on precise and dependable communication between services. This is where API specifications serve as the linchpin, establishing clear, executable contracts that dictate how services interact. With advancements in AI, we can now take these specifications and seamlessly transform them into running applications. This article explores how AI can leverage API specifications to create a robust service with a downstream dependency, emphasizing the process, benefits, and challenges of employing such a system. 

AI-Driven Application Development: A Case Study 

Here’s a practical example to illustrate the capability of agentic AI. Consider an order service that needs to interact with a product service for details like product price and description. By feeding the OpenAPI specifications of both services into an intelligent agent, the AI can generate a running application, even easing the traditionally tedious task of setting up stubs for dependencies. 

Step-by-Step Application Generation 

The AI begins by asking an LLM to generate a Node.js application for the order service. The agent then uses a suite of tools to start the order service, stubs out its product service dependency using the product service OpenAPI specification, then runs a series of contract tests against the order service. Not surprisingly, these tests may fail initially. In our example, they did fail, but this is where the power of feedback loops comes into play. 

Feedback loops provide Guardrails 

Failed tests serve as deterministic feedback for the AI. The LLM reads these failures, understands the points of contention—such as the validation of data types—and attempts to rectify them. For instance, one of the negative contract tests generated from the specification passed a null value to a discount_coupon parameter, which was a non-nullable property as per the specification. The first version of the order service accepted this value, instead of returning a 400 Bad Request response. The contract tests caught this and provided clear feedback, enabling the LLM to adjust and re-run the tests. 

Stubbing Dependencies 

One of the noteworthy aspects is how the agent manages dependencies. Given that only the order service is being generated, the product service needs to be simulated. This is achieved through dependency stubbing based on the product service’s OpenAPI specification. By creating a stub, the agent ensures that the order service can interact with a mock version of the product service, thereby validating its behavior under realistic conditions. 

Achieving a Running Application 

As the AI makes iterative adjustments based on the feedback from contract tests, it eventually gets all the tests to pass. When the tests pass, it implies that the order service is adhering correctly to the OpenAPI specification and is tuned to handle all expected data types and scenarios. 

The Role of Deterministic Feedback & Iterative Refinement 

AI systems, especially LLMs, are inherently non-deterministic and often require iterative refinement to achieve the desired outcome. This unpredictability is counterbalanced by deterministic feedback from contract tests generated from the OpenAPI specification. Each iteration of feedback and corresponding adjustments brings the application closer to full compliance with the API specifications. 

In our case, the AI underwent multiple iterations. Initially, the system generated code, executed contract tests with Specmatic, and faced failures. With each cycle, the AI learned from its mistakes, improving the application until all contract tests passed successfully. The final result was an order service that adhered strictly to its API specifications and could reliably interact with the stubbed product service. 

Advantages of Contract-Driven Development and AI 

Amalgamating AI with Contract-Driven Development, offers development teams several advantages: 

• Automated Application Creation 
  AI can autonomously generate applications based on specifications, significantly reducing manual coding effort. 

• Robust Testing 
  Contract tests ensure that the application behaves correctly, adhering to API specifications. 

• Efficient Integration 
  Dependency stubbing allows seamless inter-service communication, even when actual services are not available during the development phase. 

• Continuous Feedback 
  Deterministic tests provide ongoing feedback, enabling the AI to make necessary adjustments autonomously. 

Conclusion 

Integrating AI with contract-driven development workflows marks a significant advancement in how we build and manage microservices. By leveraging API specifications and iterative feedback loops through contract testing, we can achieve more reliable and compliant services. This approach not only accelerates development but also minimizes integration issues, ensuring that services function as intended from the outset. 

The journey from API specifications to fully functional applications is not without challenges. However, by embracing tools and methodologies that provide clear, executable contracts, we can streamline the development process, harness the power of microservices, and build systems that are both robust and agile.