Request Matching

Learn how dotMock matches incoming requests to your defined endpoints using paths, methods, and parameters.

dotMock matches incoming requests to your defined endpoints using HTTP methods, path patterns, query parameters, and headers.

How Request Matching Works

When a request arrives, dotMock follows this matching process:

Matching Process Overview

Method & Path Match

Find endpoints with matching HTTP method and path pattern

Path Parameters

Extract values from dynamic path segments

Extract Parameters

Extract query parameters and headers for use in templates

Response Rules

Evaluate conditional response rules

Return Response

Send the appropriate response or error

Path Matching Patterns

Different ways to define and match endpoint paths

Exact Path Matching

The simplest form - paths must match exactly.

Endpoint: GET /api/users

/api/users

/api/users/

/api/Users

Query Parameters

Access query parameters in your response templates

Using Query Parameters

Query parameters are automatically extracted and available in your response templates.

Example Request

GET /api/users?page=2&limit=10&sort=name

Template Usage

{
  "page": {{.page | default 1}},
  "limit": {{.limit | default 20}},
  "sort": "{{.sort | default 'id'}}",
  "users": [...]
}

Request Headers

Access request headers in your response templates

Using Request Headers

Headers from incoming requests can be referenced in your response templates.

Common Headers

Authorization: {{.headers.Authorization}}User-Agent: {{.headers.User-Agent}}X-Request-ID: {{.headers.X-Request-ID}}

Example Usage

{
  "requestId": "{{.headers.X-Request-ID | default (uuid)}}",
  "userAgent": "{{.headers.User-Agent}}",
  "authenticated": {{if .headers.Authorization}}true{{else}}false{{end}}
}

Matching Priority

When multiple endpoints could match, dotMock uses these priority rules

Priority Order

1
Exact matches
Static paths without parameters
2
Paths with parameters
Dynamic paths like /users/{id}
3
Wildcard paths
Paths with * or ** patterns

Within each priority level, the most specific match wins.

When No Endpoint Matches

Default 404 response when no endpoint matches the request

404 Not Found Response

When dotMock can't find a matching endpoint, it returns:

{
  "error": "Not Found",
  "message": "No endpoint matches GET /api/unknown",
  "statusCode": 404,
  "timestamp": "{{now}}",
  "path": "/api/unknown",
  "method": "GET"
}

Best Practices

•

Start with exact path matches, then add dynamic segments as needed

•

Use path parameters for resource identifiers (e.g., /users/{id})

•

Use query parameters for filtering and pagination

•

Test your endpoints with various edge cases and parameters

•

Be mindful of matching priority when using wildcards