Enhancing API Integration Efficiency With a Mock Client

Due to the rapid growth of the API industry, client-server interaction must be seamless for everyone. Dependence on live APIs during development, however, may cause delays, particularly if the APIs are currently being built or undergoing frequent changes. A mock client can be helpful for developers aiming for efficiency and reliability. 

In this article, we focus on the concept of mock clients, their significance, and how to use them for development.

What Is a Mock Client?

A mock client is a simulated client that interacts with an API based on its defined specifications without sending actual requests to a live server. It mimics the behavior of the API, allowing developers to test and develop client-side code in isolation. This approach is invaluable during the development and testing phases, as it eliminates dependencies on the actual API implementation, leading to more streamlined and error-free code integration.

Benefits of Having Mock Clients

The mock clients are not just a technical enhancement for any code generator tool, it’s a strategic move to support development efficiency and software quality. Here’s why mock clients are beneficial:

1. Early API Integration Testing

Mock clients allow developers to begin integrating and testing their code against the API even before the API is fully developed. This early testing makes sure that client-side functionality is validated upfront, reducing the risk of encountering significant issues later in the development cycle. This leads to having software quality process leverage.

2. Rapid Prototyping and Iteration

Developers can quickly prototype features and iterate based on immediate feedback using mock clients. This agility is beneficial in today’s dynamic development environments, where requirements can change rapidly.

3. Enhanced Reliability

Reduces dependencies on live APIs, minimizing issues caused by API downtime or instability during development.

Demo of Using a Mock Client

Note: Here, I have used Ballerina Swan Lake 2201.10.3 for demonstration.

For this demonstration, I chose the Ballerina language to implement my app. The Ballerina language has the Ballerina OpenAPI tool to generate a mock client based on my OpenAPI contract. 

The Ballerina OpenAPI Tool has a primary mode that allows us to generate client code from a given OpenAPI specification. Additionally, the mock client is another sub-mode that can be executed within the client mode. If your OpenAPI contract includes examples for operation responses, the mock client generation code can be executed using the OAS contract.

Step 1

First, I’m going to create a Ballerina package and a module for the mock client using this Organize Ballerina code guide.

• Create your Ballerina package using the bal new demo-mock command.
• Create a module for the mock client using the bal add mclient command.

Step 2

With this Ballerina OpenAPI tool, you can generate mock clients if your OpenAPI contract includes examples of particular operation responses. 

Then, I use this OpenAPI contract to generate the mock client. This contract has examples with responses.

OpenAPI Contract

openapi: 3.0.1
info:
  title: Convert
  version: 0.1.0
servers:
- url: "{server}:{port}/convert"
  variables:
    server:
      default: http://localhost
    port:
      default: "9000"
paths:
  /rate/{fromCurrency}/{toCurrency}:
    get:
      operationId: getRate
      parameters:
        - in: path
          name: fromCurrency
          schema:
            type: string
          required: true
        - in: path
          name: toCurrency
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Created
          content:
            application/json:
              schema:
                type: object
              examples:
                json1:
                  value:
                    toAmount: 60000
                    fromCurrency: EUR
                    toCurrency: LKR
                    fromAmount: 200
                    timestamp: 2024-07-14
        "202":
          description: Accepted
        "400":
          description: BadRequest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorPayload'
components:
  schemas:
    ErrorPayload:
      required:
      - message
      - method
      - path
      - reason
      - status
      - timestamp
      type: object
      properties:
        timestamp:
          type: string
        status:
          type: integer
          format: int64
        reason:
          type: string
        message:
          type: string
        path:
          type: string
        method:
          type: string

Then, execute the mock client generation command inside the created module mclient:

 bal openapi -i <yaml> --mode client --mock 

Example for Generated Ballerina Mock Client

// AUTO-GENERATED FILE. DO NOT MODIFY.
// This file is auto-generated by the Ballerina OpenAPI tool.


public isolated client class Client {
    # Gets invoked to initialize the `connector`.
    #
    # + config - The configurations to be used when initializing the `connector` 
    # + serviceUrl - URL of the target service 
    # + return - An error if connector initialization failed 
    public isolated function init(ConnectionConfig config =  {}, string serviceUrl = "http://localhost:9000/convert") returns error? {
        return;
    }

    # + headers - Headers to be sent with the request 
    # + return - Created 
    resource isolated function get rate/[string fromCurrency]/[string toCurrency](map<string|string[]> headers = {}) returns record {}|error {
        return {"fromCurrency": "EUR", "toCurrency": "LKR", "fromAmount": 200, "toAmount": 60000, "timestamp": "2024-07-14"};
    }
}

Step 3

Now, you can use the generated sample mock client for the app implementation, as I used in the main.bal file.

main.bal File

import ballerina/io;
import demo_mock.mclient as mc;

public function main() returns error? {
    mc:Client mclient = check new();
    record {} mappingResult = check mclient->/rate/["EUR"]/["LKR"]();
    io:println(mappingResult);
    // remain logic can be address here
}

More mock client samples can be found here.

Conclusion

Whether you’re building complex client-side applications or managing API integrations, using mock clients can transform your development experience to be seamless. As APIs continue to evolve and play an increasingly central role in software ecosystems, tools like OpenAPI’s mock client generation are essential for staying ahead in the competitive landscape.

Thank you for reading!