Specmatic Codec Hooks Demo

This sample project demonstrates how to use Specmatic's codec hooks feature with both proxy (recording) and stub (playback) modes when dealing with base64-encoded payloads. This repo contains two Spring Boot RESTful service. The consumer (customer-api) sends requests with base64-encoded JSON payloads to the provider (user-api). Specmatic is configured to decode these payloads before forwarding them to the provider during recording, and to encode them back to base64 when serving responses from the stub.

While this demo uses text/plain and base64 as an example, Specmatic is not limited to these formats. You can implement custom encoding/decoding logic in the hooks to suit your specific requirements.

All the services in this project including Specmatic stub and proxy expose HTTPS endpoints

Cleanup old recordings

rm -rf recordings

Start The Provider (HTTPS 8443)

cd user-api
mvn clean spring-boot:run

Start Specmatic in Proxy Mode (HTTPS 9443)

docker run --rm \
  -v "$(pwd):/usr/src/app" \
  -p 9443:9443 \
  specmatic/specmatic-openapi proxy \
    --port 9443 \
    --httpsKeyStore /usr/src/app/certs/hooks-demo-keystore.jks \
    --httpsKeyStorePassword changeit \
    --httpsPassword changeit \
    --httpsKeyAlias hooksdemo \
    --target 'https://host.docker.internal:8443' \
    recordings

Start The Consumer (HTTPS 8444)

cd customer-api
mvn clean spring-boot:run

Call POST /customers

curl --cacert certs/hooks-demo-cert.pem \
  -i -X POST https://localhost:8444/customers \
  -H 'Content-Type: application/json' \
  -d '{
    "fullName": "Jane Doe",
    "email": "jane@example.com",
    "password": "hunter2pwd"
  }'

Save Recordings

If you switch to the second terminal where Specmatic Proxy is running, you will see logs of the request being proxied to the provider. You will notice the content type as text/plain and the body as a base64-encoded string. Same with the response from the provider.

To generate the API Spec with examples, you will need to stop Specmatic Proxy using Ctrl+C. Proxy will generate a specification based on the API traffic and save the recordings in the recordings directory.

Start Specmatic Stub

Then start Specmatic in stub mode:

docker run -it --rm \
  -v "$(pwd):/usr/src/app" \
  -p 9443:9443 \
  specmatic/specmatic-openapi stub \
    --port 9443 \
    --httpsKeyStore /usr/src/app/certs/hooks-demo-keystore.jks \
    --httpsKeyStorePassword changeit \
    --httpsPassword changeit \
    --httpsKeyAlias hooksdemo \
    recordings/proxy_generated.yaml

Now that you've got the stub running, you can stop the provider by terminating the user-api process in the first terminal.

Run the curl command again. This time, the response will be served from the Specmatic Stub using the previously recorded data.

curl --cacert certs/hooks-demo-cert.pem \
  -i -X POST https://localhost:8444/customers \
  -H 'Content-Type: application/json' \
  -d '{
    "fullName": "Jane Doe",
    "email": "jane@example.com",
    "password": "hunter2pwd"
  }'

If you check the Specmatic Stub terminal, you will see that the request is being processed and the response is served from the stub. Again, you will notice that the content type is text/plain and the body is a base64-encoded string.

Hook Configuration

You can find the hooks setup in specmatic.yaml.

• pre_specmatic_request_processor: Used by Specmatic stub and proxy to process requests sent to Specmatic, before Specmatic processes them
• pre_specmatic_response_processor: Used by Specmatic proxy to process responses received from the provider, before Specmatic records them
• post_specmatic_response_processor: Used by Specmatic stub to process responses returned from Specmatic

Certificates In This Project

This demo uses a shared self-signed certificate so that every component (consumer, provider and Specmatic) can speak HTTPS on localhost or host.docker.internal.

You can read more about how these certificates are created in certs/README.md.

Documentation

• Processor hooks.
• Proxy
• Stub