Restinstance

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": "john@test.com"}
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": "test@test.com"}
    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": "john@test.com"}

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 |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: manykarim
• Source: manykarim/robotframework-agentskills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.