Introduction

Welcome to the VoodooCall API documentation. This service allows you to mock HTTP requests and simulate various API responses with ease. VoodooCall offers two standard access methods, headers and/or path slug, exemplified below. 

                
$ curl -X POST https://voodoocall.com/v1/x/$APIKEY/tasks/create -d '{"some_settings": true}'
# matcher found, configured to return 201 Created
201 Created

$ curl https://voodoocall.com/v1/x/catch/users/180/settings \
  --header "authorization: bearer $APIKEY" \
  --header 'voodoocall-match: {"path_regex":"/users/180", "delay": "3s", "body":{"status":"matched"}}'
# 3 seconds later...
{"status":"matched"}

Authentication

After signing up, you are assigned a default apikey, and you can create more apikeys as needed as as your account limits allow. Your apikeys are like namespaces, allowing you to logically separate different test case needs.

Authorization Headers: Bearer Token

Fetch all available mock configurations.

curl https://api.voodoocall.com/v1/x/catch/{{ some_endpoint }} --header "authorization: bearer $APIKEY"

Path Slug

Create a new mock configuration.

curl https://api.voodoocall.com/v1/x/{{$APYKEY}}/{{ some_endpoint }} --header "authorization: bearer $APIKEY"

Matchers

VoodooCall provides two ways to leverage Matchers. Matchers are expressions that are evaluated when VoodooCall receives a request at the /x/ endpoints to determine the correct behavior for response.

Matchers are configured through the VoodooCall UI, or they can be configured at the request level via the voodoocall-match HTTP header.

Using the voodoocall-match Header

The voodoocall-match header allows you to provide a JSON configuration that defines how the request should be matched for a response. The complete header uses the structure described below. Note that not all keys must be set, only set what you minimally need for matching: 


            {
              "verbs": ["GET", "POST", "DELETE"],       // HTTP methods to match
              "path_regex": "^/v1/resource/42",         // Regular expression for matching the request path
              "header_regex": "^Authorization: Bearer", // Regular expression for matching specific headers
              "body_regex": "^.*$",                     // Regular expression for matching the request body
              "delay": "2s",                            // Delay before responding (e.g., "2s" for 2 seconds)
              "return_status_code": 200,                // Status code to return
              "headers": {
                "Content-Type": ["application/json"]   // Response headers to return
              },
              "body": "{\"message\":\"Success\"}"      // Response body to return
            }

Notes:

  • The voodoocall-match header allows fine-grained control over the mock responses.
  • No keys are required. If no response is provided, 200 OK is returned by default
  • All responses will include the voodoocall-matcher-id header. A value of -1 is used if the matcher was triggered by the voodoocall-match header.
  • If no response is matched, a 204 no content is returned
  • All specified verbs and regular expressions (if set) must match the incoming request for the response to be triggered.
  • If a delay is specified, the response will wait for the given duration before returning the specified status code, headers, and body.

Use Cases

Use an apikey per "area of concern" or per team. Your apikeys should act like namespaces, keeping your mock HTTP responses organized. The two VoodooCall will leverage the apikey via slug or via header to access your catalog of Matchers. VoodooCall will iterate through your matchers, giving preference to the first matcher that validates. For this reason, Matchers defined via the UI should be in priority order.

To avoid ambiguity on matchers and which one may validate first, you can alternatively supply the voodoocall-match header through your test http client.

Between your Matcher catalog or the header, you can control how downstream services behave during integration testing without having to worry about altering resources. VoodooCall provides deterministic responses, allowing you to validate how your application behaves in light of timeouts and/or errors in addition to happy path testing.