Skip to content
Permalink
master
Switch branches/tags
Go to file
 
 
Cannot retrieve contributors at this time

Conditions

Whenever HttPlaceholder receives a request, all the conditions of all stubs are checked to see which stub corresponds to the sent request. There are condition checkers for example the URL, posted data etc. This page explains more.

Table of Contents

General

Under the "conditions" element, you describe how the request should look like. If the incoming request matches the conditions, the response will be returned.

- id: situation-03
  tenant: users-api
  conditions:
    method: GET
    url:
      path: /users
      query:
        id: 15
        filter: last_name
  response:
    statusCode: 200
    text: |
      {
        "last_name": "Jackson"
      }
    headers:
      Content-Type: application/json

This example uses both conditions. This means that when:

  • The URL path contains "/users"
  • A query string with name "id" and value "15" is sent.
  • A query string with name "filter" and value "last_name" is sent.

If all these conditions match, the response as defined under the "response" element is returned. For more information about the response element, you can read more here.

The stub also has a "tenant" field defined. This is a free text field which is optional. This field makes it possible to do operations of multiple stubs at once (e.g. delete all stubs with a specific tenant, get all stubs of a specific tenant or update all stubs of a specific tenant). To learn more about tenants, go to API.

Description

A free text field where you can specify where the stub is for. It is optional.

- id: situation-01
  description: Returns something
  conditions:
    method: GET
    url:
      path: /users
  response:
    statusCode: 200
    text: OK

Enabled

Describes whether the stub is enabled or not. If no enabled field is provided, the stub is enabled by default. Value can be true or false.

- id: is-disabled
  enabled: false
  conditions:
    method: GET
    url:
      path: /users
  response:
    text: This stub is disabled.

Priority

There are cases when a request matches multiple stub. If this is the case, you can use the "priority" element. With the priority element, you can specify which stub should be used if multiple stubs are found. The stub with the highest priority will be used. If you don't set the priority on the stub, it will be 0 by default.

- id: fallback
  priority: -1
  conditions: 
    method: GET
  response:
    statusCode: 200
    text: OK-Fallback

- id: situation-01
  conditions:
    method: GET
    url:
      path: /users
  response:
    statusCode: 200
    text: OK

In the scenario above, if you got to url http://httplaceholder/users, both stubs will be matched. Because the priority of the fallback stub is -1, the other stub will be used instead.

URI

Path

The path condition is used to check a part of the URL path (so the part after http://... and before the query string). The condition can both check on substring and regular expressions.

- id: situation-01
  conditions:
    method: GET
    url:
      path: /users
  response:
    statusCode: 200
    text: OK

Correct request

- id: situation-01
  conditions:
    method: GET
    url:
      # Now with regex. Path should exactly match /users in this case.
      path: ^/users$
  response:
    statusCode: 200
    text: OK

Correct request

Full path

This condition checker looks a lot like the path checker, but this checker also checks extra URL parameters, like the query string. The condition can both check on substring and regular expressions.

- id: situation-01
  conditions:
    method: GET
    url:
      fullPath: /users?filter=first_name
  response:
    statusCode: 200
    text: OK

Correct request

Query string

This condition checker can check the query string in a name-value collection like way. The condition can both check on substring and regular expressions.

- id: situation-01
  conditions:
    method: GET
    url:
      query:
        id: 14
        filter: last_name
  response:
    statusCode: 200
    text: OK

Correct request

Is HTTPS

This condition checker can be used to verify if a request uses HTTPS or not. To configure HttPlaceholder with HTTPS, read configuration (hint: it's not hard at all).

- id: ishttps-ok
  conditions:
    method: GET
    url:
      path: /ishttps-ok
      isHttps: true
  response:
    statusCode: 200
    text: OK

Correct request

Method

This condition checker can check the HTTP method (e.g. GET, POST, PUT, DELETE etc.).

- id: situation-01
  conditions:
    method: GET
  response:
    statusCode: 200
    text: OK

Correct request

Security

Basic authentication

This condition checker can check whether the sent basic authentication matches with the data in the stub.

- id: basic-auth
  conditions:
    method: GET
    basicAuthentication:
      username: user
      password: pass
  response:
    statusCode: 200
    text: OK

Correct request

Header

This condition checker can check whether the sent headers match with the headers in the stub. The condition can both check on substring and regular expressions.

- id: basic-auth
  conditions:
    method: GET
    headers:
      X-Api-Key: secret123
  response:
    statusCode: 200
    text: OK

Correct request

Request body

Raw body

This condition checker can check whether the posted body corresponds to the given rules in the stub. It is possible to add multiple conditions. The condition can both check on substring and regular expressions.

- id: situation-01
  conditions:
    method: POST
    url:
      path: \busers\b
    body:
      - \busername\b
      - \bjohn\b
  response:
    statusCode: 200
    text: '{"result": true}'
    headers:
      Content-Type: application/json

Correct request

{"username": "john"}

Form

The form value condition checker can check whether the posted form values correspond to the given rules in the stub. It is possible to add multiple conditions. The condition can both check on substring and regular expressions.

- id: form-ok
  conditions:
    method: POST
    url:
      path: /form
    form:
      - key: key1
        value: sjaak
      - key: key2
        value: bob
      - key: key2
        value: ducoo
  response:
    text: OK

Correct request

key1=sjaak&key2=bob&key2=ducoo

JSON

The JSON condition checker can be used to check if the posted JSON is posted according to your specified conditions. You can specify both an array or an object as input for the condition. When checking for string values in a JSON property, HttPlaceholder will use regular expressions to check if the condition is OK.

- id: json-object
  conditions:
    method: POST
    json:
      username: ^username$
      subObject:
        strValue: stringInput
        boolValue: true
        doubleValue: 1.23
        dateTimeValue: 2021-04-16T21:23:03
        intValue: 3
        nullValue: null
        arrayValue:
          - val1
          - subKey1: subValue1
            subKey2: subValue2
  response:
    text: OK JSON OBJECT!

Correct request

{
  "username": "username",
  "subObject": {
    "strValue": "stringInput",
    "boolValue": true,
    "doubleValue": 1.23,
    "dateTimeValue": "2021-04-16T21:23:03",
    "intValue": 3,
    "nullValue": null,
    "arrayValue": [
      "val1",
      {
        "subKey1": "subValue1",
        "subKey2": "subValue2"
      }
    ]
  }
}
- id: json-array
  conditions:
    method: POST
    json:
      - val1
      - 3
      - 1.46
      - 2021-04-17T13:16:54
      - stringVal: val1
        intVal: 55
  response:
    text: OK JSON ARRAY!

Correct request

[
    "val1",
    3,
    1.46,
    "2021-04-17T13:16:54",
    {
        "stringVal": "val1",
        "intVal": 55
    }
]

JSONPath

Using the JSONPath condition checker, you can check the posted JSON body to see if it contains the correct elements. It is possible to add multiple conditions.

Using a string array

- id: jpath-test
  conditions:
    method: PUT
    url:
      path: /users
    jsonPath:
      - "$.phoneNumbers[?(@.type=='iPhone')]"
  response:
    statusCode: 204

Specifying the expected value separately

The expectedValue variable of this condition can be used with regular expressions if needed.

- id: jpath-test
  conditions:This
    method: PUT
    url:
      path: /users
    jsonPath:
      - query: $.phoneNumbers[0].type
        expectedValue: iPhone
  response:
    statusCode: 204

Specifying the expected value separately and a single JSONPath string

Both JSONPath condition types can be combined.

- id: jpath-test
  conditions:
    method: PUT
    url:
      path: /users
    jsonPath:
      - $.name
      - query: $.phoneNumbers[0].type
        expectedValue: iPhone
  response:
    statusCode: 204

Correct request

{
    "name": "John",
	"phoneNumbers": [{
		"type": "iPhone",
		"number": "0123-4567-8888"
	}, {
		"type": "home",
		"number": "0123-4567-8910"
	}]
}

XPath

Using the XPath condition checker, you can check the posted XML body to see if it contains the correct elements. It is possible to add multiple conditions.

It is also possible to (pre)-set the XML namespaces of a posted XML body. If no namespaces are set in the stub, HttPlaceholder will try to fetch the namespaces itself using a regular expression.

- id: regular-xml
  conditions:
    method: POST
    url:
      path: /thingy
    headers:
      Content-Type: application/soap+xml; charset=utf-8
    xpath:
      - queryString: /object/a[text() = 'TEST']
  response:
    statusCode: 200
    text: <result>OK</result>
    headers:
      Content-Type: text/xml
- id: regular-xml
  conditions:
    method: POST
    url:
      path: /thingy
    headers:
      Content-Type: application/soap+xml; charset=utf-8
    xpath:
      - queryString: /object/a[text() = 'TEST']
        namespaces:
          soap: http://www.w3.org/2003/05/soap-envelope
          m: http://www.example.org/stock/Reddy
  response:
    statusCode: 200
    text: <result>OK</result>
    headers:
      Content-Type: text/xml

Correct request

<?xml version="1.0"?><object><a>TEST</a><b>TEST2</b></object>

Client IP validation

It is also possible to set a condition to check the the client IP. A condition can be set for a single IP address or a whole IP range.

# Client IP address validation on a single IP address
- id: client-ip-1
  conditions:
    method: GET
    url:
      path: /client-ip-1
    clientIp: 127.0.0.1
  response:
    statusCode: 200
    text: OK
# Client IP address validation on an IP range
- id: client-ip-2
  conditions:
    method: GET
    url:
      path: /client-ip-2
    clientIp: '127.0.0.0/29'
  response:
    statusCode: 200
    text: OK

Hostname

It is possible to check if a hostname in a request is correct. This condition can be used with regular expressions if needed.

# Check the hostname on full name.
- id: host-1
  conditions:
    method: GET
    host: httplaceholder.com
  response:
    statusCode: 200
    text: OK
- id: host-2
  conditions:
    method: GET
    host: http(.*)
  response:
    statusCode: 200
    text: OK