RequestDto

Overview #

RequestDto is the configuration object for making HTTP requests to external APIs. You create a RequestDto, configure it with URL, method, headers, and body, then send it using CurlSender (accessed via getSender() in connectors).

Purpose:

  • Configure HTTP requests (method, URL, headers, body)
  • Set authentication credentials
  • Control timeout behavior
  • Attach debug information for tracking

Location: orchesty-nodejs-sdk/lib/Transport/Curl/RequestDto.ts

When to Use #

You use RequestDto whenever you need to call an external API:

  • Fetching data from third-party services
  • Sending data to external systems
  • Making authenticated API calls
  • POSTing data to webhooks

Typical flow:

  1. Create RequestDto with URL and method
  2. Add headers and/or body if needed
  3. Send via this.getSender().send(requestDto)
  4. Process the response

Constructor # 

constructor(
    url: string,
    method: HttpMethods,
    debugInfo: AProcessDto,
    body?: unknown,
    headers: Record<string, string> = {}
)

Parameters #

ParameterTypeRequiredDescription
urlstringYesThe API endpoint URL
methodHttpMethodsYesHTTP method (GET, POST, PUT, etc.)
debugInfoAProcessDtoYesProcessDto for debug tracking
bodyunknownNoRequest body (optional)
headersRecord<string, string>NoInitial headers (optional)

Example # 

import RequestDto from '../../lib/Transport/Curl/RequestDto';
import { HttpMethods } from '../../lib/Transport/HttpMethods';

// Basic GET request
const requestDto = new RequestDto(
    'https://api.example.com/users',
    HttpMethods.GET,
    dto
);

// POST with body and headers
const postRequest = new RequestDto(
    'https://api.example.com/users',
    HttpMethods.POST,
    dto,
    { name: 'John', email: 'john@example.com' },
    { 'Authorization': 'Bearer token123' }
);

Core Methods #

URL Methods #

getUrl() # 

public getUrl(): string

Returns the request URL.

Returns: string - The API endpoint URL

setUrl() # 

public setUrl(url: string): this

Sets or changes the request URL.

Parameters:

ParameterTypeDescription
urlstringThe new URL

Returns: this - Fluent interface

Example:

requestDto.setUrl('https://api.example.com/v2/users');

HTTP Method Methods #

getMethod() # 

public getMethod(): HttpMethods

Returns the HTTP method.

Returns: HttpMethods - The HTTP method

setMethod() # 

public setMethod(method: HttpMethods): this

Sets or changes the HTTP method.

Parameters:

ParameterTypeDescription
methodHttpMethodsThe HTTP method (GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD)

Returns: this - Fluent interface

Example:

import { HttpMethods } from '../../lib/Transport/HttpMethods';

requestDto.setMethod(HttpMethods.PATCH);

Body Methods #

getBody() # 

public getBody(): unknown

Returns the request body.

Returns: unknown - The request body

setBody() # 

public setBody(body: unknown): this

Sets the request body (raw).

Parameters:

ParameterTypeDescription
bodyunknownThe request body

Returns: this - Fluent interface

Example:

requestDto.setBody('raw string data');

setJsonBody() # 

public setJsonBody(body: unknown): this

Sets the request body as JSON (automatically stringifies).

Parameters:

ParameterTypeDescription
bodyunknownObject to be JSON-stringified

Returns: this - Fluent interface

Example:

requestDto.setJsonBody({
    userId: 123,
    action: 'update',
    data: {
        name: 'John Doe',
        email: 'john@example.com'
    }
});

Header Methods #

getHeaders() # 

public getHeaders(): Record<string, string>

Returns all headers.

Returns: Record<string, string> - Headers object

setHeaders() # 

public setHeaders(headers: Record<string, string>): this

Replaces all headers.

Parameters:

ParameterTypeDescription
headersRecord<string, string>New headers object

Returns: this - Fluent interface

Example:

requestDto.setHeaders({
    'Content-Type': 'application/json',
    'Authorization': 'Bearer token123',
    'X-API-Key': 'my-api-key'
});

addHeaders() # 

public addHeaders(headers: Record<string, string>): this

Merges additional headers (doesn't replace existing).

Parameters:

ParameterTypeDescription
headersRecord<string, string>Headers to add/merge

Returns: this - Fluent interface

Example:

// Add headers without replacing existing ones
requestDto.addHeaders({
    'X-Custom-Header': 'value',
    'X-Request-ID': '12345'
});

Authentication Methods #

setAuth() # 

public setAuth(username: string, password: string): void

Sets HTTP Basic Authentication credentials.

Parameters:

ParameterTypeDescription
usernamestringUsername for basic auth
passwordstringPassword for basic auth

Example:

requestDto.setAuth('myUsername', 'myPassword');

getAuth() # 

public getAuth(): { username: string; password: string } | undefined

Returns the authentication credentials.

Returns: { username: string; password: string } | undefined - Auth object or undefined

Timeout Methods #

setTimeout() # 

public setTimeout(ms: number): this

Sets the request timeout in milliseconds.

Parameters:

ParameterTypeDescription
msnumberTimeout in milliseconds

Returns: this - Fluent interface

Default: 30000 ms (30 seconds)

Example:

// Set 60 second timeout
requestDto.setTimeout(60000);

getTimeout() # 

public getTimeout(): number

Returns the request timeout.

Returns: number - Timeout in milliseconds

Debug Methods #

setDebugInfo() # 

public setDebugInfo(dto: AProcessDto): this

Sets debug information for request tracking.

Parameters:

ParameterTypeDescription
dtoAProcessDtoProcessDto with tracking info

Returns: this - Fluent interface

Example:

requestDto.setDebugInfo(dto);

getDebugInfo() # 

public getDebugInfo(): AProcessDto

Returns the debug information.

Returns: AProcessDto - Debug info

Usage Examples #

Basic GET Request # 

import RequestDto from '../../lib/Transport/Curl/RequestDto';
import { HttpMethods } from '../../lib/Transport/HttpMethods';

export default class GetUsersConnector extends AConnector {
    
    public async processAction(dto: ProcessDto): Promise<ProcessDto> {
        // Create GET request
        const requestDto = new RequestDto(
            'https://api.example.com/users',
            HttpMethods.GET,
            dto
        );
        
        // Send request
        const responseDto = await this.getSender().send(requestDto);
        
        // Get response
        const users = JSON.parse(responseDto.getBody());
        dto.setJsonData({ users });
        
        return dto;
    }
}

POST with JSON Body # 

public async processAction(dto: ProcessDto): Promise<ProcessDto> {
    const input = dto.getJsonData();
    
    // Create POST request with JSON body
    const requestDto = new RequestDto(
        'https://api.example.com/users',
        HttpMethods.POST,
        dto
    );
    
    // Set JSON body
    requestDto.setJsonBody({
        name: input.name,
        email: input.email,
        role: 'user'
    });
    
    // Send request
    const responseDto = await this.getSender().send(requestDto);
    const createdUser = JSON.parse(responseDto.getBody());
    
    dto.setJsonData({ user: createdUser });
    return dto;
}

Authenticated Request # 

import CoreFormsEnum from '../../lib/Application/Base/CoreFormsEnum';

public async processAction(dto: ProcessDto): Promise<ProcessDto> {
    // Get API credentials
    const appInstall = await this.getApplicationInstallFromProcess(dto);
    const apiKey = appInstall.getSettings()[CoreFormsEnum.AUTHORIZATION_FORM]['api_key'];
    
    // Create request with authentication header
    const requestDto = new RequestDto(
        'https://api.example.com/protected/data',
        HttpMethods.GET,
        dto
    );
    
    // Add authorization header
    requestDto.setHeaders({
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
    });
    
    const responseDto = await this.getSender().send(requestDto);
    dto.setData(responseDto.getBody());
    
    return dto;
}

Custom Headers # 

public async processAction(dto: ProcessDto): Promise<ProcessDto> {
    const requestDto = new RequestDto(
        'https://api.example.com/data',
        HttpMethods.GET,
        dto
    );
    
    // Set multiple headers
    requestDto.setHeaders({
        'X-API-Key': 'your-api-key',
        'X-Request-ID': dto.getHeader('correlation-id'),
        'Accept': 'application/json',
        'User-Agent': 'OrchestySDK/1.0'
    });
    
    // Or add headers incrementally
    requestDto.addHeaders({
        'X-Custom-Header': 'custom-value'
    });
    
    const responseDto = await this.getSender().send(requestDto);
    dto.setData(responseDto.getBody());
    
    return dto;
}

With Timeout # 

public async processAction(dto: ProcessDto): Promise<ProcessDto> {
    const requestDto = new RequestDto(
        'https://slow-api.example.com/data',
        HttpMethods.GET,
        dto
    );
    
    // Set 2 minute timeout for slow endpoint
    requestDto.setTimeout(120000);
    
    try {
        const responseDto = await this.getSender().send(requestDto);
        dto.setData(responseDto.getBody());
    } catch (error) {
        if (error.message.includes('timeout')) {
            dto.setStopProcess(
                ResultCode.STOP_AND_FAILED,
                'Request timed out after 2 minutes'
            );
        }
    }
    
    return dto;
}

Multiple Parallel Requests #

From: orchesty-nodejs-sdk/test/Connector/TestConnector.ts

public async processAction(dto: ProcessDto): Promise<ProcessDto> {
    // Make multiple requests in parallel
    await Promise.all(
        [1, 2, 3].map(async (page) => {
            const requestDto = new RequestDto(
                `https://api.example.com/users?page=${page}`,
                HttpMethods.GET,
                dto,
                '',
                { 'X-Custom-Header': 'value' }
            );
            
            requestDto.setDebugInfo(dto);
            const responseDto = await this.getSender().send(requestDto);
            const data = responseDto.getBody();
            
            console.log(`Page ${page}:`, data);
        })
    );
    
    dto.setJsonData({
        message: 'All pages fetched',
        timestamp: Date.now()
    });
    
    return dto;
}

Common Patterns #

Pattern 1: Dynamic URL Construction # 

public async processAction(dto: ProcessDto): Promise<ProcessDto> {
    const input = dto.getJsonData();
    const baseUrl = 'https://api.example.com';
    
    // Build URL with parameters
    const url = `${baseUrl}/users/${input.userId}/orders/${input.orderId}`;
    
    const requestDto = new RequestDto(url, HttpMethods.GET, dto);
    const responseDto = await this.getSender().send(requestDto);
    
    dto.setData(responseDto.getBody());
    return dto;
}

Pattern 2: Conditional Headers # 

public async processAction(dto: ProcessDto): Promise<ProcessDto> {
    const appInstall = await this.getApplicationInstallFromProcess(dto);
    const settings = appInstall.getSettings()[CoreFormsEnum.AUTHORIZATION_FORM];
    
    const requestDto = new RequestDto(
        'https://api.example.com/data',
        HttpMethods.GET,
        dto
    );
    
    // Add headers based on configuration
    const headers: Record<string, string> = {
        'Content-Type': 'application/json'
    };
    
    if (settings.use_api_key) {
        headers['X-API-Key'] = settings.api_key;
    } else if (settings.use_bearer) {
        headers['Authorization'] = `Bearer ${settings.token}`;
    }
    
    requestDto.setHeaders(headers);
    
    const responseDto = await this.getSender().send(requestDto);
    dto.setData(responseDto.getBody());
    
    return dto;
}

Pattern 3: PUT/PATCH with JSON # 

public async processAction(dto: ProcessDto): Promise<ProcessDto> {
    const input = dto.getJsonData();
    
    const requestDto = new RequestDto(
        `https://api.example.com/users/${input.userId}`,
        HttpMethods.PATCH,
        dto
    );
    
    requestDto.setHeaders({
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${input.apiKey}`
    });
    
    requestDto.setJsonBody({
        name: input.newName,
        email: input.newEmail,
        updatedAt: new Date().toISOString()
    });
    
    const responseDto = await this.getSender().send(requestDto);
    dto.setJsonData({
        updated: true,
        user: JSON.parse(responseDto.getBody())
    });
    
    return dto;
}

Pattern 4: Query Parameters # 

public async processAction(dto: ProcessDto): Promise<ProcessDto> {
    const input = dto.getJsonData();
    
    // Build URL with query parameters
    const params = new URLSearchParams({
        limit: '10',
        offset: input.offset || '0',
        sort: 'created_at',
        order: 'desc'
    });
    
    const url = `https://api.example.com/users?${params.toString()}`;
    
    const requestDto = new RequestDto(url, HttpMethods.GET, dto);
    const responseDto = await this.getSender().send(requestDto);
    
    dto.setData(responseDto.getBody());
    return dto;
}

Next Steps #

Now that you understand RequestDto, explore related topics:

  1. AConnector - Use RequestDto in connectors
  2. ProcessDto - Work with data and context
  3. ApplicationInstall - Access API credentials
  4. ResponseDto - Handle API responses
  5. CurlSender - Send requests

See Also #

© 2025 Orchesty Solutions. All rights reserved.