restinstance

name	restinstance
description	Guide AI agents in creating REST API tests using RESTinstance library. Use when building API tests with JSON Schema validation, built-in assertions, response field validation, and OpenAPI spec integration.

RESTinstance Library Skill

Quick Reference

RESTinstance is a REST API testing library with built-in JSON validation, schema support, and OpenAPI/Swagger spec integration. It provides a fluent interface for API testing with automatic response validation.

Installation

pip install RESTinstance

Library Import

*** Settings ***
Library    REST    ${API_URL}

Key Differentiators from RequestsLibrary

Feature	RESTinstance	RequestsLibrary
Built-in assertions	Yes	No (use RF assertions)
JSON Schema validation	Yes	No (need JSONLibrary)
OpenAPI/Swagger support	Yes	No
Response type validation	Yes (String, Integer, etc.)	Manual
State management	Automatic instance tracking	Session-based

Basic Usage

Simple GET Request

GET    /users/1
Integer    response status    200
String     response body name    John
Integer    response body id    1

POST with JSON Body

POST    /users    {"name": "John", "email": "[e-mail]"}
Integer    response status    201
Integer    response body id
String     response body name    John

Complete CRUD Example

*** Test Cases ***
CRUD User Lifecycle
    # Create
    POST    /users    {"name": "John"}
    Integer    response status    201
    ${id}=    Integer    response body id

    # Read
    GET    /users/${id}
    Integer    response status    200
    String    response body name    John

    # Update
    PUT    /users/${id}    {"name": "John Updated"}
    Integer    response status    200
    String    response body name    John Updated

    # Delete
    DELETE    /users/${id}
    Integer    response status    204

Core Keywords Quick Reference

HTTP Methods

Keyword	Usage	Description
GET	GET /endpoint	GET request
POST	POST /endpoint {"json": "body"}	POST with JSON
PUT	PUT /endpoint {"json": "body"}	Replace resource
PATCH	PATCH /endpoint {"json": "body"}	Partial update
DELETE	DELETE /endpoint	Delete resource
HEAD	HEAD /endpoint	Headers only
OPTIONS	OPTIONS /endpoint	Get allowed methods

Response Validation Keywords

Keyword	Usage	Description
Integer	Integer response status 200	Validate integer value
String	String response body name John	Validate string value
Number	Number response body price 19.99	Validate float/number
Boolean	Boolean response body active true	Validate boolean
Null	Null response body deleted_at	Validate null value
Array	Array response body items	Validate array type
Object	Object response body profile	Validate object type
Output	Output response body	Log value (must exist)
Missing	Missing response body error	Validate field absent

Response Validation

Status Code

GET    /users/1
Integer    response status    200

POST    /users    {"name": "Test"}
Integer    response status    201

DELETE    /users/1
Integer    response status    204

Body Fields

GET    /users/1

# Validate type only (any value)
String     response body name
Integer    response body id
Boolean    response body active

# Validate type AND value
String     response body name    John
Integer    response body age     30
Boolean    response body active  true

Nested Fields

# Response: {"user": {"profile": {"name": "John"}}}
GET    /users/1
String    response body user profile name    John
Integer   response body user id              1

Array Access

# Response: {"items": [{"id": 1}, {"id": 2}]}
GET    /items
Integer    response body items 0 id    1
Integer    response body items 1 id    2
String     response body items 0 name

Field Existence

GET    /users/1
Output     response body id      # Field must exist (logs value)
Missing    response body error   # Field must NOT exist

Headers and Authentication

Set Headers

Set Headers    {"Authorization": "Bearer ${TOKEN}"}
GET    /protected

Per-Request Headers

GET    /data    headers={"X-Custom": "value"}

Basic Auth

${credentials}=    Evaluate    base64.b64encode(b'${USER}:${PASS}').decode()    modules=base64
Set Headers    {"Authorization": "Basic ${credentials}"}
GET    /protected

Bearer Token

Set Headers    {"Authorization": "Bearer ${TOKEN}"}
GET    /users/me
Integer    response status    200

JSON Schema Validation

Inline Schema

GET    /users/1
Object    response body    {"type": "object", "required": ["id", "name"]}

Schema From File (Using Expect Response Body)

# Set expectation BEFORE the request
Expect Response Body    ${CURDIR}/schemas/user.json
GET    /users/1

Example Schema File (user.json)

{
  "type": "object",
  "required": ["id", "name", "email"],
  "properties": {
    "id": {"type": "integer"},
    "name": {"type": "string", "minLength": 1},
    "email": {"type": "string", "format": "email"},
    "active": {"type": "boolean"}
  }
}

Pattern Matching

Wildcard Matching

String    response body name    John*        # Starts with John
String    response body type    *_active     # Ends with _active
String    response body id      *abc*        # Contains abc

Regex Matching

String    response body email    /^[\\w.-]+@[\\w.-]+\\.\\w+$/
String    response body phone    /^\\+?\\d{10,}$/
String    response body uuid     /^[a-f0-9-]{36}$/

Common Patterns

API Test Structure

*** Settings ***
Library    REST    https://api.example.com

*** Test Cases ***
Get User By ID
    GET    /users/1
    Integer    response status    200
    String     response body name
    Integer    response body id    1
    Missing    response body error

Create User Successfully
    POST    /users    {"name": "Test", "email": "[e-mail]"}
    Integer    response status    201
    String     response body name    Test
    Integer    response body id

Store and Reuse Values

*** Test Cases ***
Create And Verify User
    POST    /users    {"name": "John"}
    ${id}=    Integer    response body id

    GET    /users/${id}
    Integer    response body id    ${id}
    String     response body name    John

Validate Response Headers

GET    /users
String    response headers Content-Type    application/json*

Expectation Keywords (Schema Validation)

The correct way to validate responses against JSON Schema files is using expectation keywords BEFORE the HTTP request:

Expect Response Body

# Validate response body against a JSON Schema file
Expect Response Body    ${CURDIR}/schemas/user.json
GET    /users/1

Expect Response

# Validate the full response (status, headers, body) against a schema
Expect Response    ${CURDIR}/schemas/response.json
GET    /users/1

Expect Request

# Validate request body before sending
Expect Request    ${CURDIR}/schemas/create-user-request.json
POST    /users    {"name": "John", "email": "[e-mail]"}

Clear Expectations

# Remove all previously set expectations
Clear Expectations
GET    /users/1    # No schema validation on this request

Client Configuration Keywords

SSL and Certificate Configuration

# Disable SSL verification
Set SSL Verify    ${False}
GET    /users

# Set client certificate for mTLS
Set Client Cert    ${CURDIR}/certs/client.pem
GET    /protected

# Set client authentication
Set Client Authentication    ${USERNAME}    ${PASSWORD}
GET    /protected

Query Parameters

# Pass query parameters as a dict using the query parameter
&{params}=    Create Dictionary    page=1    limit=10
GET    /users    query=${params}
# Results in: GET /users?page=1&limit=10

Disabling Automatic Validation

# Disable automatic schema validation for a single request
GET    /users/1    validate=False

When to Load Additional References

Load these reference files for specific use cases:

• JSON Schema validation patterns -> references/schema-validation.md
• JSON handling and manipulation -> references/json-handling.md
• OAuth, JWT, API keys -> references/authentication.md
• Full keyword listing -> references/keywords-reference.md
• Error debugging -> references/troubleshooting.md

Companion Skills

Need	Skill
Generate user keywords	keyword-builder
Generate test cases	testcase-builder
Design resource file layout	resource-architect
Search for keywords across libraries	libdoc-search
Explain keyword arguments in detail	libdoc-explain
Parse test results from output.xml	results