Skip to main content
Yasumu’s REST module provides a complete solution for designing and testing HTTP APIs. All requests are stored as .ysl files in your workspace, making them easy to version and share.

​
Creating a REST request

1

Open your workspace

Make sure you have an active workspace open in Yasumu.
2

Create new request

Click “New Request” or use the keyboard shortcut to create a new REST request.
3

Configure request details

Set the HTTP method, URL, headers, and body for your request.
4

Execute request

Click “Send” to execute the request and view the response.

​
REST request structure

Each request is stored as a .ysl file in the yasumu/rest/ directory: 
@rest

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

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

dependencies []

script {
  export function onRequest() {
    // Pre-request logic here
  }
}

​
Programmatic REST operations

​
Creating a request

Use the RestModule.create() method to create requests programmatically: 
const request = await workspace.rest.create({
  name: 'Get User',
  method: 'GET',
  url: 'https://api.example.com/users/123',
  headers: [
    { key: 'Authorization', value: 'Bearer token', enabled: true },
    { key: 'Content-Type', value: 'application/json', enabled: true }
  ],
  searchParameters: [
    { key: 'include', value: 'profile', enabled: true }
  ],
  requestParameters: [],
  body: null,
  groupId: null // or group ID to organize
});

console.log(`Created request: ${request.name}`);
console.log(`Request ID: ${request.id}`);

​
Listing requests

// Get all REST requests as entities
const requests = await workspace.rest.list();

for (const request of requests) {
  console.log(`${request.method} ${request.name}`);
}

​
Getting a specific request

// Get request by ID
const request = await workspace.rest.get('request-id-here');

console.log(request.name);   // Request name
console.log(request.method); // HTTP method (GET, POST, etc.)
console.log(request.url);    // Request URL

​
Updating a request

// Update request properties
await request.update({
  name: 'Get User Profile',
  url: 'https://api.example.com/users/profile',
  method: 'POST'
});

// Or use convenience methods
await request.setName('Updated Name');
await request.setUrl('https://new-url.com');
await request.setMethod('PUT');

​
Deleting a request

// Delete a request
await request.delete();

// Or delete by ID
await workspace.rest.delete('request-id-here');

​
HTTP methods

Yasumu supports all standard HTTP methods:
  • GET - Retrieve resources
  • POST - Create resources
  • PUT - Update/replace resources
  • PATCH - Partially update resources
  • DELETE - Remove resources
  • HEAD - Get headers only
  • OPTIONS - Get supported methods

​
Request configuration

​
URL parameters

Use path parameters with colon syntax: 
await workspace.rest.create({
  name: 'Get User by ID',
  method: 'GET',
  url: 'https://api.example.com/users/:userId',
  requestParameters: [
    { key: 'userId', value: '123', enabled: true }
  ]
});
The :userId in the URL will be replaced with 123 at runtime, resulting in: 
https://api.example.com/users/123

​
Query parameters

Add search parameters to your requests: 
await workspace.rest.create({
  name: 'Search Users',
  method: 'GET',
  url: 'https://api.example.com/users',
  searchParameters: [
    { key: 'page', value: '1', enabled: true },
    { key: 'limit', value: '50', enabled: true },
    { key: 'sort', value: 'name', enabled: true }
  ]
});
Result: https://api.example.com/users?page=1&limit=50&sort=name

​
Request headers

const request = await workspace.rest.create({
  name: 'Authenticated Request',
  method: 'POST',
  url: 'https://api.example.com/data',
  headers: [
    { key: 'Authorization', value: 'Bearer {{TOKEN}}', enabled: true },
    { key: 'Content-Type', value: 'application/json', enabled: true },
    { key: 'X-Custom-Header', value: 'custom-value', enabled: true }
  ]
});

​
Request body

For requests that support a body (POST, PUT, PATCH): 
await workspace.rest.create({
  name: 'Create User',
  method: 'POST',
  url: 'https://api.example.com/users',
  headers: [
    { key: 'Content-Type', value: 'application/json', enabled: true }
  ],
  body: {
    type: 'json',
    content: JSON.stringify({
      name: 'John Doe',
      email: '[email protected]'
    })
  }
});

​
Pre-request and post-response scripts

Yasumu allows you to run TypeScript code before sending requests or after receiving responses: 
script {
  export function onRequest() {
    // Run before request is sent
    const timestamp = Date.now();
    return {
      headers: {
        'X-Request-Time': timestamp.toString()
      }
    };
  }

  export function onResponse(response) {
    // Run after response is received
    console.log('Status:', response.status);
    console.log('Body:', response.body);

    // Store data for later use
    const data = JSON.parse(response.body);
    // Save to environment variable
  }
}

​
Execute scripts programmatically

// Execute pre-request script
const result = await workspace.rest.executeScript(
  request.id,
  request.data.script,
  {
    request: {
      url: request.url,
      method: request.method,
      headers: request.data.headers
    }
  }
);

// Execute post-response script
await workspace.rest.executeScript(
  request.id,
  request.data.script,
  {
    request: { /* ... */ },
    response: {
      status: 200,
      headers: {},
      body: '{ "success": true }'
    }
  }
);

​
Request history

Yasumu tracks request execution history: 
// List all request history
const history = await workspace.rest.listHistory();

// Add current request to history
const historyEntry = await workspace.rest.upsertHistory(request.id);

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

​
Using environment variables

Reference environment variables in your requests using {{VARIABLE_NAME}}: 
await workspace.rest.create({
  name: 'API Call with Variables',
  method: 'GET',
  url: '{{API_URL}}/users/{{USER_ID}}',
  headers: [
    { key: 'Authorization', value: 'Bearer {{API_TOKEN}}', enabled: true }
  ]
});
See the environment variables guide for more details.

​
Best practices

  • Descriptive names: Use clear, descriptive names for requests
  • Organize with groups: Use folders to organize related requests
  • Environment variables: Store URLs and tokens as variables
  • Disable unused parameters: Toggle enabled: false instead of deleting
  • Use scripts: Automate repetitive tasks with pre/post scripts
  • Track history: Review past executions to debug issues

​
Next steps

Environment variables

Manage dynamic values in requests

Testing emails

Test email workflows with SMTP

Build docs developers (and LLMs) love

Get started for freeTalk to us