REST API testing

Yasumu provides a powerful REST API testing module that allows you to create, organize, and execute HTTP requests. All REST entities are stored as .ysl files in your workspace, making them easy to version control and share with your team.

Creating REST requests

REST requests in Yasumu are called “entities” and are stored in the yasumu/rest/ directory. Each entity is a separate .ysl file containing the request configuration, scripts, and tests.

Basic request structure

Here’s a typical REST entity file:

@rest

metadata {
  name: "Get User Profile"
  method: "GET"
  id: "cmwulsxe1z3ade8hbjgcguvd"
  groupId: "mv2z3sr80ai1cv2axxap3juq"
}

request {
  url: "{{API_URL}}/users/{{userId}}"
  headers: [
    {
      key: "Authorization"
      value: "Bearer {{ACCESS_TOKEN}}"
      enabled: true
    },
    {
      key: "Content-Type"
      value: "application/json"
      enabled: true
    }
  ]
  parameters: []
  searchParameters: [
    {
      key: "include"
      value: "profile,settings"
      enabled: true
    }
  ]
  body: null
}

dependencies []

script {
  export function onRequest() {
    console.log('Preparing request...');
  }
}

Request components

Metadata
Request
Scripts
Tests

The metadata block defines the request’s identity and organization:

metadata {
  name: "Get User Profile"    # Display name
  method: "GET"               # HTTP method
  id: "unique-id"             # Unique identifier
  groupId: "parent-group"     # Optional group assignment
}

Supported HTTP methods: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS

The request block contains all request configuration:

request {
  url: "https://api.example.com/endpoint"
  headers: []              # Request headers
  parameters: []           # Path parameters
  searchParameters: []     # Query parameters
  body: null               # Request body
}

Headers

Key-value pairs sent with the request:

headers: [
  {
    key: "Authorization"
    value: "Bearer token"
    enabled: true
  }
]

Path parameters

Replace :parameter placeholders in the URL:

url: "https://api.example.com/users/:userId"
parameters: [
  {
    key: "userId"
    value: "12345"
    enabled: true
  }
]

Search parameters

Query string parameters appended to the URL:

searchParameters: [
  {
    key: "page"
    value: "1"
    enabled: true
  },
  {
    key: "limit"
    value: "20"
    enabled: true
  }
]

Request body

Payload for POST, PUT, and PATCH requests:

body: {
  type: "application/json"
  content: "'{"name": "John Doe", "email": "[email protected]"}'"
}

The script block contains pre-request and post-response scripts:

script {
  export function onRequest(req, res) {
    // Executed before sending the request
    req.headers.set('X-Timestamp', Date.now().toString());
  }
  
  export function onResponse(req, res) {
    // Executed after receiving the response
    console.log('Status:', res.status);
  }
}

Learn more about scripting.

The test block contains test assertions:

test {
  console.log("Testing response...");
}

Working with the REST module

Yasumu’s core library provides a comprehensive API for managing REST entities:

import { RestModule } from '@yasumu/core';

// Create a new REST entity
const entity = await workspace.rest.create({
  name: 'Get User Profile',
  method: 'GET',
  url: 'https://api.example.com/users/{{userId}}',
  groupId: null,
  headers: [
    { key: 'Authorization', value: 'Bearer {{token}}', enabled: true }
  ],
  searchParameters: [],
  requestParameters: [],
  body: null,
  script: { code: '', language: 'typescript' },
});

Organizing requests with groups

Groups help organize related requests into logical collections:

// Create a new group
const group = await workspace.rest.createEntityGroup({
  name: 'User Management',
  entity: 'rest',
  parentId: null,
  workspaceId: workspace.id,
});

// Create request in group
const entity = await workspace.rest.create({
  name: 'Create User',
  method: 'POST',
  groupId: group.id,
  // ... other properties
});

// Update group
await workspace.rest.updateEntityGroup(group.id, {
  name: 'Updated Group Name',
});

// Delete group
await workspace.rest.deleteEntityGroup(group.id);

Environment variable interpolation

Use double curly braces {{variable}} to reference environment variables:

Define variables

Create environment variables in your workspace:

const env = await workspace.environments.create({
  name: 'Development',
});

env.variables.set('API_URL', 'https://api.dev.example.com');
env.variables.set('USER_ID', '12345');

Reference in requests

Use variables in your REST entity:

request {
  url: "{{API_URL}}/users/{{USER_ID}}"
  headers: [
    {
      key: "Authorization"
      value: "Bearer {{ACCESS_TOKEN}}"
      enabled: true
    }
  ]
}

Variables are interpolated

When executing the request, variables are automatically replaced with their values from the active environment.

Executing requests

// Execute pre-request script
const context = {
  request: entity.data,
  environment: env.toJSON(),
  workspace: workspace.toJSON(),
};

const result = await entity.executePreRequestScript(context);

if (result.success) {
  console.log('Script executed successfully');
} else {
  console.error('Script error:', result.error);
}

Request history

Yasumu automatically tracks request execution history:

// List request history
const history = await workspace.rest.listHistory();

history.forEach(item => {
  console.log(`${item.entityId} - Last executed: ${item.lastExecutedAt}`);
});

// Add to history
await workspace.rest.upsertHistory(entity.id);

// Clear history for a request
await workspace.rest.deleteHistory(entity.id);

Advanced features

Mock responses

Return custom responses without making actual HTTP requests:

script {
  export function onRequest() {
    const res = new YasumuResponse(
      'Hello World!',
      { status: 200, statusText: 'OK' }
    );
    return res;
  }
}

Request dependencies

Define dependencies between requests to ensure proper execution order:

dependencies [
  "auth-request-id",
  "setup-request-id"
]

Best practices

Use environment variables: Never hardcode API URLs, tokens, or sensitive data. Use environment variables and secrets instead.

Organize with groups: Create logical groups for different API domains, versions, or features.

Descriptive names: Use clear, descriptive names that explain what each request does.

Enable/disable parameters: Use the enabled flag to temporarily disable headers or parameters without deleting them.

Be careful when executing scripts that modify global state or make side effects. Scripts run in an isolated environment but can still affect your request context.

Next steps

Scripting

Learn how to write pre-request and post-response scripts

Environments

Manage environment variables and secrets

Schema Language

Deep dive into the .ysl format

Email Testing

Test email functionality with SMTP

Get Started

Core Concepts

Features

Guides

REST API testing

Creating REST requests

Basic request structure

Request components

Working with the REST module

Organizing requests with groups

Environment variable interpolation

Executing requests

Request history

Advanced features

Mock responses

Request dependencies

Best practices

Next steps

Scripting

Environments

Schema Language

Email Testing

Build docs developers (and LLMs) love

Get Started

Core Concepts

Features

Guides

​Creating REST requests

​Basic request structure

​Request components

​Working with the REST module

​Organizing requests with groups

​Environment variable interpolation

​Executing requests

​Request history

​Advanced features

Mock responses

Request dependencies

​Best practices

​Next steps

Scripting

Environments

Schema Language

Email Testing

Build docs developers (and LLMs) love

Creating REST requests

Basic request structure

Request components

Working with the REST module

Organizing requests with groups

Environment variable interpolation

Executing requests

Request history

Advanced features

Best practices

Next steps