Conditional rules

With the Conditional rules strategy, an endpoint looks at each request and picks a response to match: a token for the right password, 401 for the wrong one. This page explains conditions, lists every source and operator, and builds a login endpoint step by step.

How rules are evaluated

1. Responses are checked from top to bottom.
2. A response is chosen when every one of its conditions matches the request.
3. The first response that is chosen is sent. Later ones are not checked.
4. A response with no conditions is the default response (fallback). It is sent when no other response matches.

Each response card shows a block at the top. It reads Use this response when… when the response has conditions, and Default response (fallback) when it has none.

Good to know

The fallback does not have to be last. Responses without conditions are skipped during the top-to-bottom check and only used when nothing else matched. If several responses have no conditions, the first of them is the fallback. If every response has conditions and none matches, the first response in the list is sent.

Add a condition

1. Under How should this endpoint respond?, select Conditional rules.

2. On a response card, select Add condition.

3. Choose the source: where in the request to look.

4. Type the key: which query parameter, header, path parameter or body field.

5. Choose the operator, and type the value to compare with.

Add more conditions to the same response to narrow it. An AND marker appears between them: every condition must match, not only one. Select the remove button on a condition to delete it.

Sources

The source says which part of the request to read.

Source	Key to type	Example
Query param	The parameter name	page for /users?page=2
Header	The header name	X-API-Key
Path param	The parameter name, without the colon	id for /users/:id
Body field (JSON path)	A dotted path to a field	user.role
HTTP method	Not used	Value POST

Notes on each source:

• Query param. Names and values are case-sensitive.
• Header. Header names are not case-sensitive, so x-api-key and X-API-Key are the same. The value is compared exactly.
• Path param. Use the name from the endpoint's path. For * and ** the names are wildcard0 and rest.
• Body field (JSON path). The request body must be a JSON object. Use dots for nested fields: user.role reads admin from {"user": {"role": "admin"}}. The path follows objects only; it cannot step into a list by position. Values are compared as text, so the number 5 is 5 and the boolean true is true.
• HTTP method. The value is the method in capitals. It is useful when the endpoint's method is ANY.

Operators

Operator	Matches when	Example
equals	The value is exactly the same. Case-sensitive.	page equals 2
does not equal	The value is different, or missing.	status does not equal active
contains	Your text appears anywhere in the value.	User-Agent contains Mobile
exists	The value is present and not empty. No value needed.	Authorization exists
matches regex	A regular expression matches the value.	^[0-9]+$ for digits only
greater than	Both are numbers and the value is larger.	quantity greater than 10
less than	Both are numbers and the value is smaller.	age less than 18

Notes:

• does not equal also matches when the field is missing altogether. Add an exists condition to the same response if the field must be present.
• matches regex can match anywhere in the value. Anchor the pattern with ^ and $ to match the whole value. A pattern that is not a valid regular expression never matches.
• greater than and less than compare as numbers. A value that is not a number never matches.

Worked example: login that returns 200 or 401

The sample project has this endpoint as Login (conditional). Building it yourself shows every step.

1. Add a Blank endpoint. Set the method to POST, the path to /login and the name to Login.

2. Select Conditional rules.

3. On the first response, set Label to Success, Status to 200, and the body to:

   {
     "token": "{{uuid}}",
     "expiresIn": 3600
   }

4. On the same response, select Add condition. Choose Body field (JSON path), type the key password, keep equals, and type the value secret.

5. Select Add response. Set its Label to Invalid credentials, Status to 401, and the body to:

   {
     "error": "invalid_credentials"
   }

   Leave it with no conditions. Its block reads Default response (fallback).

Start the server and try both cases:

curl -i -X POST http://localhost:8080/login \
  -H 'Content-Type: application/json' \
  -d '{"email": "ana@example.com", "password": "secret"}'

The first line of the output is HTTP/1.1 200 OK, and the body is:

{
  "token": "5f0c2c36-8a7e-4d43-9a55-0f1e2b3c4d5e",
  "expiresIn": 3600
}

Now send a wrong password:

curl -i -X POST http://localhost:8080/login \
  -H 'Content-Type: application/json' \
  -d '{"email": "ana@example.com", "password": "wrong"}'

This time the first line is HTTP/1.1 401 Unauthorized, and the body is:

{
  "error": "invalid_credentials"
}

You can also test it without a terminal. In the test row, open Request body, edit the JSON and select Send. See Built-in tester.

More examples

Admins only. Endpoint GET /admin/reports:

Label	Conditions	Status
Allowed	Header X-Role equals admin	200
Forbidden	none (fallback)	403

Two conditions together. Endpoint GET /orders. The first response is sent only for page 2 of the shipped orders:

Label	Conditions	Status
Shipped, page 2	Query param status equals shipped AND Query param page equals 2	200
Everything else	none (fallback)	200

Validation error. Endpoint POST /orders:

Label	Conditions	Status
Too many	Body field (JSON path) quantity greater than 100	422
Created	none (fallback)	201

One path, several methods. Endpoint ANY /items:

Label	Conditions	Status
Created	HTTP method equals POST	201
Deleted	HTTP method equals DELETE	204
List	none (fallback)	200

Either-or conditions

Conditions inside one response are always joined with AND. To send the same response when either of two things is true, Duplicate the response and give each copy one of the conditions.

Check which rule fired

Open Live in the rail. Each row shows the endpoint name and the label of the response that was sent, such as Login · Invalid credentials. If the wrong response is sent, check:

• the order of the responses, since the first full match wins;
• upper and lower case in values, since equals is case-sensitive;
• that the request body is valid JSON. A body that is not a JSON object has no fields to read.

Next steps

• Response strategies
• Dynamic templating
• Negative testing
• Auth testing