<?xml version="1.0" encoding="UTF-8"?>
<keywordspec name="REST" type="library" format="ROBOT" generated="20200529 11:03:36">
<version></version>
<scope>test suite</scope>
<namedargs>yes</namedargs>
<doc>RESTinstance is revolutionary and peaceful HTTP JSON API test library.

It guides you to write more stable API tests relying on constraints (e.g. "people's email addresses must be valid"), rather than on values having the nature of change (e.g "the first created user's email is expected to stay foo@bar.com").

It bases on observations that we are more often concerned whether and which properties changed, when they should (not) had as this signals a bug, and less often what the actual values were/are. This also helps in tackling tests failing only because the test environment data was (not) reset.

These resolutions in mind, it walks the path with you to contract-driven testing, from automatically generated JSON Schema data models to having formal OpenAPI service specs, as the both are essentially of the same origin. Both are also supported by major forces (Google, Microsoft, IBM et al. founded OpenAPI Initiative), and are language-agnostic which goes as well with Robot Framework.

Contracts represent a common language within software teams, recognising our differing talents as designers, developers and test experts; or perhaps your new business companion wants to integrate to the system as well, but there is still some noise in signal - yet you don't feel very content providing them the source code, let alone explaining technical details, like which JSON properties are must in the response body, over the phone.

Rest your mind. OSS got your back.


= Tutorial =

There is a [https://github.com/asyrjasalo/RESTinstance/blob/master/examples/README.rst|step-by-step tutorial] in the making on using the library.

For RESTful APIs, this library is intended to be used so that a test suite
is dedicated per endpoint. The test suite is divided into test cases so that
the differing operations (implemented by the endpoint via HTTP methods)
are tested with separate test cases.


= The state =

The library represents its own state as JSON itself, as an array of objects.
Together these objects are commonly called instances.

A single instance always has these three properties:

- Request data as a JSON object
- Response data as a JSON object
- JSON Schema for the above two properties

For each request-response, as soon as the response has been gotten
(and the request did not timeout), a new instance is created with these
properties.

Request and response schemas are inferred if they are not already
expected by using expectation keywords. All the validations the library
implements are based on JSON Schema [http://json-schema.org/draft-07/json-schema-validation.html|draft-07] by default
but also [http://json-schema.org/draft-06/json-schema-validation.html|draft-06] and
[http://json-schema.org/draft-04/json-schema-validation.html|draft-04] can be configured.

= The scope =

All the assertion keywords, `Output` and `Output Schema` are effective
in the scope of the last instance.

The scope of the library itself is test suite, meaning the instances
are persisted in memory until the execution of the test suite is finished,
regardless whether successfully or not.

The last request and response is easiest seen with `Output`.
The output is written to terminal by default, as this is usually faster
for debugging purposes than finding the right keyword in ``log.html``.

All instances can be output to a file with `RESTinstances` which can
be useful for additional logging.</doc>
<init>
<arguments>
<arg>url=None</arg>
<arg>ssl_verify=True</arg>
<arg>accept=application/json, */*</arg>
<arg>content_type=application/json</arg>
<arg>user_agent=RESTinstance/1.0.0rc4</arg>
<arg>proxies={}</arg>
<arg>schema={}</arg>
<arg>spec={}</arg>
<arg>instances=[]</arg>
</arguments>
<doc>Initialize self.  See help(type(self)) for accurate signature.</doc>
<tags>
</tags>
</init>
<kw name="Array">
<arguments>
<arg>field</arg>
<arg>*enum</arg>
<arg>**validations</arg>
</arguments>
<doc>*Asserts the field as JSON array.*

The field consists of parts separated by spaces, the parts being
object property names or array indices starting from 0, and the root
being the instance created by the last request (see `Output` for it).

For asserting deeply nested properties or multiple objects at once,
[http://goessner.net/articles/JsonPath|JSONPath] can be used with
[https://github.com/h2non/jsonpath-ng#jsonpath-syntax|supported JSONPath expressions],
the root being the response body.

*Enum*

The allowed values for the property as zero or more arguments.
If none given, the value of the property is not asserted.

*Validations*

The JSON Schema validation keywords
[https://json-schema.org/understanding-json-schema/reference/array.html|for array]
can be used. Validations are optional but update the schema of
the property (more accurate) if given.
`Output Schema` can be used for the current schema of the field.

The keyword will fail if any of the given validations fail.
Given validations can be skipped altogether by adding ``skip=true``.
When skipped, the schema is updated but the validations are not ran.
Skip is intented mainly for debugging the updated schema before aborting.

*Examples*
| `GET`  | /users?_limit=10 | | | | # https://jsonplaceholder.typicode.com/users |
| `Array` | response body | | |
| `Array` | $ | | | | # same as above |
| `Array` | $ | minItems=1 | maxItems=10 | uniqueItems=true |</doc>
<tags>
<tag>assertions</tag>
</tags>
</kw>
<kw name="Boolean">
<arguments>
<arg>field</arg>
<arg>value=None</arg>
<arg>**validations</arg>
</arguments>
<doc>*Asserts the field as JSON boolean.*

The field consists of parts separated by spaces, the parts being
object property names or array indices starting from 0, and the root
being the instance created by the last request (see `Output` for it).

For asserting deeply nested properties or multiple objects at once,
[http://goessner.net/articles/JsonPath|JSONPath] can be used with
[https://github.com/h2non/jsonpath-ng#jsonpath-syntax|supported JSONPath expressions], the root being the response body.

*Value*

If given, the property value is validated in addition to the type.

*Validations*

The JSON Schema validation keywords
[https://json-schema.org/understanding-json-schema/reference/generic.html|common for all types]
can be used. Validations are optional but update the schema of
the property (more accurate) if given.
`Output Schema` can be used for the current schema of the field.

The keyword will fail if any of the given validations fail.
Given validations can be skipped altogether by adding ``skip=true``.
When skipped, the schema is updated but the validations are not ran.
Skip is intented mainly for debugging the updated schema before aborting.

*Examples*

| `PUT`  | /users/1 | { "verified_email": true } | | | # https://jsonplaceholder.typicode.com/users/1 |
| `Boolean` | response body verified_email | | | | # value is optional |
| `Boolean` | response body verified_email | true |
| `Boolean` | response body verified_email | ${True} | | | # same as above |
| `Boolean` | $.verified_email | true | | | # JSONPath alternative |
| `Boolean` | $.verified_email | true | enum=[1, "1"] | skip=true | # would pass |</doc>
<tags>
<tag>assertions</tag>
</tags>
</kw>
<kw name="Clear Expectations">
<arguments>
</arguments>
<doc>*Resets the expectations for both request and response.*

Using this keyword resets any expectations set with keywords
`Expect Response`, `Expect Response Body` and `Expect Request`.</doc>
<tags>
<tag>expectations</tag>
</tags>
</kw>
<kw name="Delete">
<arguments>
<arg>endpoint</arg>
<arg>timeout=None</arg>
<arg>allow_redirects=None</arg>
<arg>validate=True</arg>
<arg>headers=None</arg>
</arguments>
<doc>*Sends a DELETE request to the endpoint.*

The endpoint is joined with the URL given on library init (if any).
If endpoint starts with ``http://`` or ``https://``, it is assumed
an URL outside the tested API (which may affect logging).

*Options*

``timeout``: A number of seconds to wait for the response before failing the keyword.

``allow_redirects``: If false, do not follow any redirects.

``validate``: If false, skips any request and response validations set
by expectation keywords and a spec given on library init.

``headers``: Headers as a JSON object to add or override for the request.

*Examples*

| `DELETE` | /users/6 |
| `DELETE` | http://localhost:8273/state | validate=false |</doc>
<tags>
<tag>http</tag>
</tags>
</kw>
<kw name="Expect Request">
<arguments>
<arg>schema</arg>
<arg>merge=False</arg>
</arguments>
<doc>*Sets the schema to validate the request properties*

Expectations are effective for following requests in the test suite,
or until they are reset or updated by using expectation keywords again.
On the test suite level (suite setup), they are best used for expecting
the endpoint wide properties that are common regardless of the tested
HTTP method, and on the test case level (test setup) to merge in
the HTTP method specific properties.

`Expect Request` is intented to be used with tests that have some of the
request properties, e.g. body or query parameters, randomized ("fuzzing")
for validating that the sent values are within the expected scope.

If the keyword is used, following HTTP keywords will fail when
their request properties are not valid against the expected schema.

If the keyword is not used, a new schema is generated for each following
request for its ``body`` and ``query`` properties. Use `Output Schema` to output it and use it as an input to this keyword.

*Options*

``merge``: Merges the new schema with the current instead of replacing it

*Examples*

| `Expect Request` | ${CURDIR}/valid_payload.json | | # See `Output Schema` |
| `Expect Request` | { "body": { "required": ["id"] } } | merge=true |</doc>
<tags>
<tag>expectations</tag>
</tags>
</kw>
<kw name="Expect Response">
<arguments>
<arg>schema</arg>
<arg>merge=False</arg>
</arguments>
<doc>*Sets the schema to validate the response properties.*

Expectations are effective for following requests in the test suite,
or until they are reset or updated by using expectation keywords again.
On the test suite level (suite setup), they are best used for expecting
the endpoint wide properties that are common regardless of the tested
HTTP method, and on the test case level (test setup) to merge in
the HTTP method specific properties.

`Expect Response` is intented to be used on the suite level to validate
the endpoint properties that hold regardless of the HTTP method,
such as body property types, responded headers, authentication, etc.

If the keyword is used, following HTTP keywords will fail when
their response properties are not valid against the expected schema.

If the keyword is not used, a new schema is inferred for each following
response for its ``body``. Use `Output Schema` to output it and use it
as an input to this keyword.

*Options*

``merge``: Merges the new schema with the current instead of replacing it

*Examples*

| `Expect Response` | ${CURDIR}/endpoint_data_model.json | | # See `Output Schema` |
| `Expect Response` | { "headers": { "required": ["Via"] } } | merge=true |
| `Expect Response` | { "seconds": { "maximum": "1.0" } } | merge=true |</doc>
<tags>
<tag>expectations</tag>
</tags>
</kw>
<kw name="Expect Response Body">
<arguments>
<arg>schema</arg>
</arguments>
<doc>*Updates the schema to validate the response body properties.*

Expectations are effective for following requests in the test suite,
or until they are reset or updated by using expectation keywords again.
On the test suite level (suite setup), they are best used for expecting
the endpoint wide properties that are common regardless of the tested
HTTP method, and on the test case level (test setup) to merge in
the HTTP method specific properties.

`Expect Response Body` is intented to be used on the test case level,
to validate that the response body has the expected properties for
the particular HTTP method. Note that if something about response body
has been already expected with `Expected Response`, using this keyword
updates the expectations in terms of given response body properties.

If the keyword is used, following HTTP keywords will fail if
their response body is not valid against the expected schema.

If the keyword is not used, and no schema is already expected with
`Expect Response` for response ``body``, a new schema is inferred for it.
Use `Output Schema` to output it and use it as an input to this keyword.

*Tips*

Regardless whether the HTTP method returns one (an object) or many
(an array of objects), the validation of the object property types and features can usually be done to some extent on the test suite level
with `Expect Response`, then extended on the test case level using this
keyword. This helps in ensuring that the data model is unified between
the different HTTP methods.

*Examples*

| `Expect Response Body` | ${CURDIR}/user_properties.json | # See `Output Schema` |
| `Expect Response Body` | { "required": ["id", "token"] } | # Only these are required from this method |
| `Expect Response Body` | { "additionalProperties": false } | # Nothing extra should be responded by this method |</doc>
<tags>
<tag>expectations</tag>
</tags>
</kw>
<kw name="Get">
<arguments>
<arg>endpoint</arg>
<arg>query=None</arg>
<arg>timeout=None</arg>
<arg>allow_redirects=None</arg>
<arg>validate=True</arg>
<arg>headers=None</arg>
</arguments>
<doc>*Sends a GET request to the endpoint.*

The endpoint is joined with the URL given on library init (if any).
If endpoint starts with ``http://`` or ``https://``, it is assumed
an URL outside the tested API (which may affect logging).

*Options*

``query``: Request query parameters as a JSON object or a dictionary.
Alternatively, query parameters can be given as part of endpoint as well.

``timeout``: A number of seconds to wait for the response before failing the keyword.

``allow_redirects``: If false, do not follow any redirects.

``validate``: If false, skips any request and response validations set
by expectation keywords and a spec given on library init.

``headers``: Headers as a JSON object to add or override for the request.

*Examples*

| `GET` | /users/1 |
| `GET` | /users | timeout=2.5 |
| `GET` | /users?_limit=2 |
| `GET` | /users | _limit=2 |
| `GET` | /users | { "_limit": "2" } |
| `GET` | https://jsonplaceholder.typicode.com/users | headers={ "Authentication": "" } |</doc>
<tags>
<tag>http</tag>
</tags>
</kw>
<kw name="Head">
<arguments>
<arg>endpoint</arg>
<arg>timeout=None</arg>
<arg>allow_redirects=None</arg>
<arg>validate=True</arg>
<arg>headers=None</arg>
</arguments>
<doc>*Sends a HEAD request to the endpoint.*

The endpoint is joined with the URL given on library init (if any).
If endpoint starts with ``http://`` or ``https://``, it is assumed
an URL outside the tested API (which may affect logging).

*Options*

``timeout``: A number of seconds to wait for the response before failing the keyword.

``allow_redirects``: If true, follow all redirects.
In contrary to other methods, no HEAD redirects are followed by default.

``validate``: If false, skips any request and response validations set
by expectation keywords and a spec given on library init.

``headers``: The headers to add or override for this request.

*Examples*

| `HEAD` | /users/1 |
| `HEAD` | /users/1 | timeout=0.5 |</doc>
<tags>
<tag>http</tag>
</tags>
</kw>
<kw name="Input">
<arguments>
<arg>what</arg>
</arguments>
<doc>*Converts the input to JSON and returns it.*

Any of the following is accepted:

- The path to JSON file
- Any scalar that can be interpreted as JSON
- A dictionary or a list

*Examples*

| ${payload} | `Input` | ${CURDIR}/payload.json |

| ${object} | `Input` | { "name": "Julie Langford", "username": "jlangfor" } |
| ${object} | `Input` | ${dict} |

| ${array} | `Input` | ["name", "username"] |
| ${array} | `Input` | ${list} |

| ${boolean} | `Input` | true |
| ${boolean} | `Input` | ${True} |

| ${number} | `Input` | 2.0 |
| ${number} | `Input` | ${2.0} |

| ${string} | `Input` | Quotes are optional for strings |</doc>
<tags>
<tag>I/O</tag>
</tags>
</kw>
<kw name="Integer">
<arguments>
<arg>field</arg>
<arg>*enum</arg>
<arg>**validations</arg>
</arguments>
<doc>*Asserts the field as JSON integer.*

The field consists of parts separated by spaces, the parts being
object property names or array indices starting from 0, and the root
being the instance created by the last request (see `Output` for it).

For asserting deeply nested properties or multiple objects at once,
[http://goessner.net/articles/JsonPath|JSONPath] can be used with
[https://github.com/h2non/jsonpath-ng#jsonpath-syntax|supported JSONPath expressions],
the root being the response body.

*Enum*

The allowed values for the property as zero or more arguments.
If none given, the value of the property is not asserted.

*Validations*

The JSON Schema validation keywords
[https://json-schema.org/understanding-json-schema/reference/numeric.html#integer|for numeric types]
can be used. Validations are optional but update the schema of
the property (more accurate) if given.
`Output Schema` can be used for the current schema of the field.

The keyword will fail if any of the given validations fail.
Given validations can be skipped altogether by adding ``skip=true``.
When skipped, the schema is updated but the validations are not ran.
Skip is intented mainly for debugging the updated schema before aborting.

*Examples*

| `GET`  | /users/1 | | # https://jsonplaceholder.typicode.com/users/1 |
| `Integer` | response body id | | # value is optional |
| `Integer` | response body id | 1 |
| `Integer` | response body id | ${1} | # same as above |
| `Integer` | $.id | 1 | # JSONPath alternative |

| `GET`  | /users?_limit=10 | | | | # https://jsonplaceholder.typicode.com/users |
| `Integer` | response body 0 id | 1 | | |
| `Integer` | $[0].id | 1 | | | # same as above |
| `Integer` | $[*].id | | minimum=1 | maximum=10 |</doc>
<tags>
<tag>assertions</tag>
</tags>
</kw>
<kw name="Missing">
<arguments>
<arg>field</arg>
</arguments>
<doc>*Asserts the field does not exist.*

The field consists of parts separated by spaces, the parts being
object property names or array indices starting from 0, and the root
being the instance created by the last request (see `Output` for it).

For asserting deeply nested properties or multiple objects at once,
[http://goessner.net/articles/JsonPath|JSONPath] can be used with
[https://github.com/h2non/jsonpath-ng#jsonpath-syntax|supported JSONPath expressions],
the root being the response body.

*Examples*

| `GET`     | /users/1 | # https://jsonplaceholder.typicode.com/users/1 |
| `Missing` | response body password |
| `Missing` | $.password |
| `Missing` | $..geo.elevation | # response body address geo elevation |

| `GET`     | /users | # https://jsonplaceholder.typicode.com/users |
| `Missing` | response body 0 password |
| `Missing` | $[*].password |
| `Missing` | $[*]..geo.elevation |</doc>
<tags>
<tag>assertions</tag>
</tags>
</kw>
<kw name="Null">
<arguments>
<arg>field</arg>
<arg>**validations</arg>
</arguments>
<doc>*Asserts the field as JSON null.*

The field consists of parts separated by spaces, the parts being
object property names or array indices starting from 0, and the root
being the instance created by the last request (see `Output` for it).

For asserting deeply nested properties or multiple objects at once,
[http://goessner.net/articles/JsonPath|JSONPath] can be used with
[https://github.com/h2non/jsonpath-ng#jsonpath-syntax|supported JSONPath expressions],
the root being the response body.

*Validations*

The JSON Schema validation keywords
[https://json-schema.org/understanding-json-schema/reference/generic.html|common for all types]
can be used. Validations are optional but update the schema of
the property (more accurate) if given.
`Output Schema` can be used for the current schema of the field.

The keyword will fail if any of the given validations fail.
Given validations can be skipped altogether by adding ``skip=true``.
When skipped, the schema is updated but the validations are not ran.
Skip is intented mainly for debugging the updated schema before aborting.

*Examples*

| `PUT`  | /users/1 | { "deactivated_at": null } | # https://jsonplaceholder.typicode.com/users/1 |
| `Null` | response body deactivated_at | |
| `Null` | $.deactivated_at | | # JSONPath alternative |</doc>
<tags>
<tag>assertions</tag>
</tags>
</kw>
<kw name="Number">
<arguments>
<arg>field</arg>
<arg>*enum</arg>
<arg>**validations</arg>
</arguments>
<doc>*Asserts the field as JSON number.*

The field consists of parts separated by spaces, the parts being
object property names or array indices starting from 0, and the root
being the instance created by the last request (see `Output` for it).

For asserting deeply nested properties or multiple objects at once,
[http://goessner.net/articles/JsonPath|JSONPath] can be used with
[https://github.com/h2non/jsonpath-ng#jsonpath-syntax|supported JSONPath expressions],
the root being the response body.

*Enum*

The allowed values for the property as zero or more arguments.
If none given, the value of the property is not asserted.

*Validations*

The JSON Schema validation keywords
[https://json-schema.org/understanding-json-schema/reference/numeric.html#number|for numeric types] can be used. Validations are optional but update the schema of
the property (more accurate) if given.
`Output Schema` can be used for the current schema of the field.

The keyword will fail if any of the given validations fail.
Given validations can be skipped altogether by adding ``skip=true``.
When skipped, the schema is updated but the validations are not ran.
Skip is intented mainly for debugging the updated schema before aborting.

*Examples*

| `PUT`  | /users/1 | { "allocation": 95.0 } | # https://jsonplaceholder.typicode.com/users/1 |
| `Number` | response body allocation | | # value is optional |
| `Number` | response body allocation | 95.0 |
| `Number` | response body allocation | ${95.0} | # same as above |
| `Number` | $.allocation | 95.0 | # JSONPath alternative |

| `GET`  | /users?_limit=10 | | | | # https://jsonplaceholder.typicode.com/users |
| `Number` | $[0].id | 1 | | | # integers are also numbers |
| `Number` | $[*].id | | minimum=1 | maximum=10 |</doc>
<tags>
<tag>assertions</tag>
</tags>
</kw>
<kw name="Object">
<arguments>
<arg>field</arg>
<arg>*enum</arg>
<arg>**validations</arg>
</arguments>
<doc>*Asserts the field as JSON object.*

The field consists of parts separated by spaces, the parts being
object property names or array indices starting from 0, and the root
being the instance created by the last request (see `Output` for it).

For asserting deeply nested properties or multiple objects at once,
[http://goessner.net/articles/JsonPath|JSONPath] can be used with
[https://github.com/h2non/jsonpath-ng#jsonpath-syntax|supported JSONPath expressions], the root being the response body.

*Enum*

The allowed values for the property as zero or more arguments.
If none given, the value of the property is not asserted.

*Validations*

The JSON Schema validation keywords
[https://json-schema.org/understanding-json-schema/reference/object.html|for object]
can be used. Validations are optional but update the schema of
the property (more accurate) if given.
`Output Schema` can be used for the current schema of the field.

The keyword will fail if any of the given validations fail.
Given validations can be skipped altogether by adding ``skip=true``.
When skipped, the schema is updated but the validations are not ran.
Skip is intented mainly for debugging the updated schema before aborting.

*Examples*

| `GET`  | /users/1 | | # https://jsonplaceholder.typicode.com/users/1 |
| `Object` | response body | |
| `Object` | response body | required=["id", "name"] | # can have other properties |

| `GET`  | /users/1 | | # https://jsonplaceholder.typicode.com/users/1 |
| `Object` | $.address.geo | required=["lat", "lng"] |
| `Object` | $..geo | additionalProperties=false | # cannot have other properties |</doc>
<tags>
<tag>assertions</tag>
</tags>
</kw>
<kw name="Options">
<arguments>
<arg>endpoint</arg>
<arg>timeout=None</arg>
<arg>allow_redirects=None</arg>
<arg>validate=True</arg>
<arg>headers=None</arg>
</arguments>
<doc>*Sends an OPTIONS request to the endpoint.*

The endpoint is joined with the URL given on library init (if any).
If endpoint starts with ``http://`` or ``https://``, it is assumed
an URL outside the tested API (which may affect logging).

*Options*

``timeout``: A number of seconds to wait for the response before failing the keyword.

``allow_redirects``: If false, do not follow any redirects.

``validate``: If false, skips any request and response validations set
by expectation keywords and a spec given on library init.

``headers``: Headers as a JSON object to add or override for the request.

*Examples*

| `OPTIONS` | /users/1 |
| `OPTIONS` | /users/1 | allow_redirects=false |</doc>
<tags>
<tag>http</tag>
</tags>
</kw>
<kw name="Output">
<arguments>
<arg>what=</arg>
<arg>file_path=None</arg>
<arg>append=False</arg>
<arg>sort_keys=False</arg>
</arguments>
<doc>*Outputs JSON to terminal or a file.*

By default, the last request and response are output to terminal.

The output can be limited further by:

- The property of the last instance, e.g. ``request`` or ``response``
- Any nested property that exists, similarly as for assertion keywords

Also variables and values that can be converted to JSON are accepted,
in which case those are output as JSON instead.

*Options*

``file_path``: The JSON is written to a file instead of terminal.
The file is created if it does not exist.

``append``: If true, the JSON is appended to the given file
instead of truncating it first.

``sort_keys``: If true, the JSON is sorted alphabetically by
property names before it is output.

*Examples*

| `Output` | response | # only the response is output |
| `Output` | response body | # only the response body is output |
| `Output` | $.email | # only the response body property is output |
| `Output` | $..geo | # only the nested response body property is output |

| `Output` | request | # only the request is output |
| `Output` | request headers | # only the request headers are output |
| `Output` | request headers Authentication | # only this header is output |

| `Output` | response body | ${CURDIR}/response_body.json | | # write the response body to a file |
| `Output` | response seconds | ${CURDIR}/response_delays.log | append=true | # keep track of response delays in a file |</doc>
<tags>
<tag>I/O</tag>
</tags>
</kw>
<kw name="Output Schema">
<arguments>
<arg>what=</arg>
<arg>file_path=None</arg>
<arg>append=False</arg>
<arg>sort_keys=False</arg>
</arguments>
<doc>*Outputs JSON Schema to terminal or a file.*

By default, the schema is output for the last request and response.

The output can be limited further by:

- The property of the last instance, e.g. ``request`` or ``response``
- Any nested property that exists, similarly as for assertion keywords

Also variables and values that can be converted to JSON are accepted,
in which case the schema is generated for those instead.

*Options*

``file_path``: The JSON Schema is written to a file instead of terminal.
The file is created if it does not exist.

``append``: If true, the JSON Schema is appended to the given file
instead of truncating it first.

``sort_keys``: If true, the JSON Schema is sorted alphabetically by
property names before it is output.

*Examples*

| `Output Schema` | response | ${CURDIR}/response_schema.json | # Write a file to use with `Expect Response` |
| `Output Schema` | response body | ${CURDIR}/response_body_schema.json | # Write a file to use with `Expect Response Body` |

| `Output Schema` | $.email | # only the schema for one response body property |
| `Output Schema` | $..geo | # only the schema for the nested response body property |</doc>
<tags>
<tag>I/O</tag>
</tags>
</kw>
<kw name="Patch">
<arguments>
<arg>endpoint</arg>
<arg>body=None</arg>
<arg>timeout=None</arg>
<arg>allow_redirects=None</arg>
<arg>validate=True</arg>
<arg>headers=None</arg>
</arguments>
<doc>*Sends a PATCH request to the endpoint.*

The endpoint is joined with the URL given on library init (if any).
If endpoint starts with ``http://`` or ``https://``, it is assumed
an URL outside the tested API (which may affect logging).

*Options*

``body``: Request body parameters as a JSON object, file or a dictionary.

``timeout``: A number of seconds to wait for the response before failing the keyword.

``allow_redirects``: If false, do not follow any redirects.

``validate``: If false, skips any request and response validations set
by expectation keywords and a spec given on library init.

``headers``: Headers as a JSON object to add or override for the request.

*Examples*

| `PATCH` | /users/4 | { "name": "Clementine Bauch" } |
| `PATCH` | /users/4 | ${dict} |</doc>
<tags>
<tag>http</tag>
</tags>
</kw>
<kw name="Post">
<arguments>
<arg>endpoint</arg>
<arg>body=None</arg>
<arg>timeout=None</arg>
<arg>allow_redirects=None</arg>
<arg>validate=True</arg>
<arg>headers=None</arg>
</arguments>
<doc>*Sends a POST request to the endpoint.*

The endpoint is joined with the URL given on library init (if any).
If endpoint starts with ``http://`` or ``https://``, it is assumed
an URL outside the tested API (which may affect logging).

*Options*

``body``: Request body parameters as a JSON object, file or a dictionary.

``timeout``: A number of seconds to wait for the response before failing the keyword.

``allow_redirects``: If false, do not follow any redirects.

``validate``: If false, skips any request and response validations set
by expectation keywords and a spec given on library init.

``headers``: Headers as a JSON object to add or override for the request.

*Examples*

| `POST` | /users | { "id": 11, "name": "Gil Alexander" } |
| `POST` | /users | ${CURDIR}/new_user.json |</doc>
<tags>
<tag>http</tag>
</tags>
</kw>
<kw name="Put">
<arguments>
<arg>endpoint</arg>
<arg>body=None</arg>
<arg>timeout=None</arg>
<arg>allow_redirects=None</arg>
<arg>validate=True</arg>
<arg>headers=None</arg>
</arguments>
<doc>*Sends a PUT request to the endpoint.*

The endpoint is joined with the URL given on library init (if any).
If endpoint starts with ``http://`` or ``https://``, it is assumed
an URL outside the tested API (which may affect logging).

*Options*

``body``: Request body parameters as a JSON object, file or a dictionary.

``timeout``: A number of seconds to wait for the response before failing the keyword.

``allow_redirects``: If false, do not follow any redirects.

``validate``: If false, skips any request and response validations set
by expectation keywords and a spec given on library init.

``headers``: Headers as a JSON object to add or override for the request.

*Examples*

| `PUT` | /users/2 | { "name": "Julie Langford", "username": "jlangfor" } |
| `PUT` | /users/2 | ${dict} |</doc>
<tags>
<tag>http</tag>
</tags>
</kw>
<kw name="Rest Instances">
<arguments>
<arg>file_path=None</arg>
<arg>sort_keys=False</arg>
</arguments>
<doc>*Writes the instances as JSON to a file.*

The instances are written to file as a JSON array of JSON objects,
each object representing a single instance, and having three properties:

- the request
- the response
- the schema for both, which have been updated according to the tests

The file is created if it does not exist, otherwise it is truncated.

*Options*

``sort_keys``: If true, the instances are sorted alphabetically by
property names.

*Examples*

| `Rest Instances` | ${CURDIR}/log.json |</doc>
<tags>
<tag>I/O</tag>
</tags>
</kw>
<kw name="Set Client Cert">
<arguments>
<arg>cert</arg>
</arguments>
<doc>*Sets the client cert for the requests.*

The cert is either a path to a .pem file, or a JSON array, or a list
having the cert path and the key path.

Values ``null`` and ``${None}`` can be used for clearing the cert.

*Examples*

| `Set Client Cert` | ${CURDIR}/client.pem |
| `Set Client Cert` | ["${CURDIR}/client.cert", "${CURDIR}/client.key"] |
| `Set Client Cert` | ${paths_list} |</doc>
<tags>
<tag>settings</tag>
</tags>
</kw>
<kw name="Set Headers">
<arguments>
<arg>headers</arg>
</arguments>
<doc>*Sets new request headers or updates the existing.*

``headers``: The headers to add or update as a JSON object or a
dictionary.

*Examples*

| `Set Headers` | { "authorization": "Basic QWxhZGRpbjpPcGVuU2VzYW1"} |
| `Set Headers` | { "Accept-Encoding": "identity"} |
| `Set Headers` | ${auth_dict} |</doc>
<tags>
<tag>settings</tag>
</tags>
</kw>
<kw name="String">
<arguments>
<arg>field</arg>
<arg>*enum</arg>
<arg>**validations</arg>
</arguments>
<doc>*Asserts the field as JSON string.*

The field consists of parts separated by spaces, the parts being
object property names or array indices starting from 0, and the root
being the instance created by the last request (see `Output` for it).

For asserting deeply nested properties or multiple objects at once,
[http://goessner.net/articles/JsonPath|JSONPath] can be used with
[https://github.com/h2non/jsonpath-ng#jsonpath-syntax|supported JSONPath expressions], the root being the response body.

*Enum*

The allowed values for the property as zero or more arguments.
If none given, the value of the property is not asserted.

*Validations*

The JSON Schema validation keywords
[https://json-schema.org/understanding-json-schema/reference/string.html|for string]
can be used. Validations are optional but update the schema of
the property (more accurate) if given.
`Output Schema` can be used for the current schema of the field.

The keyword will fail if any of the given validations fail.
Given validations can be skipped altogether by adding ``skip=true``.
When skipped, the schema is updated but the validations are not ran.
Skip is intented mainly for debugging the updated schema before aborting.

*Examples*

| `GET`  | /users/1 | | | # https://jsonplaceholder.typicode.com/users/1 |
| `String` | response body email | | | # value is optional |
| `String` | response body email | Sincere@april.biz |
| `String` | $.email | Sincere@april.biz | | # JSONPath alternative |
| `String` | $.email | | format=email |

| `GET`  | /users?_limit=10 | | | # https://jsonplaceholder.typicode.com/users |
| `String` | response body 0 email | Sincere@april.biz |
| `String` | $[0].email | Sincere@april.biz | | # same as above |
| `String` | $[*].email | | format=email |</doc>
<tags>
<tag>assertions</tag>
</tags>
</kw>
</keywordspec>
