name: robotframework-restinstance-skill
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

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": "[email protected]"}
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

Response Validation Keywords

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

GET    /users/1
Output Schema    response body    ${CURDIR}/schemas/user.json

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": "[email protected]"}
    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*

When to Load Additional References

Load these reference files for specific use cases:

• Instance state management -> references/instance-management.md
• All request keywords -> references/request-keywords.md
• Deep response validation -> references/response-validation.md
• JSON Schema patterns -> references/json-schema-validation.md
• OAuth, JWT, API keys -> references/authentication.md
• OpenAPI/Swagger testing -> references/spec-driven-testing.md
• Error debugging -> references/troubleshooting.md