Creating Requests

Configure request handlers with dynamic responses using special entities

What is a Request?

A Request (also called a request handler) defines how your mock endpoint responds to incoming HTTP requests. Each endpoint can have multiple requests that match different HTTP methods, parameters, or other criteria.

Example: An endpoint /users/{id} might have separate request handlers for GET (retrieve user), PUT (update user), and DELETE (delete user) methods.

Creating a Request Handler

Step 1: Access the Request Form

  1. Navigate to your endpoint's detail page
  2. Click "Add Request" or the "+" button
  3. Or create a request while creating an endpoint by enabling "With request details"

Step 2: Configure Request Details

Method

The HTTP method this request handler responds to.

GET

Retrieve data

POST

Create new resource

PUT / PATCH

Update resource

DELETE

Remove resource

Accept

The Accept header value.

application/json
application/xml
text/html
*/*

Content Type

Response Content-Type header.

application/json
application/xml
text/plain
text/html

Parameters

JSON object representing request parameters that must match.

{
  "page": "1",
  "limit": "10",
  "sort": "desc"
}

Response

The response body that will be returned. This is where you can use special entities to generate dynamic data!

💡 AI Generation: Click the "Generate with AI" button to automatically create realistic response data.

Status

HTTP status code:

  • 200 OK
  • 201 Created
  • 400 Bad Request
  • 404 Not Found

Delay

Response delay (ms):

  • 0 Instant
  • 500 0.5s
  • 1000 1s
  • 3000 3s

Is enabled?

Toggle to enable/disable this request handler without deleting it.

Special Entities

Special entities are placeholder tags that EchoMock replaces with dynamic values each time the endpoint is called. This allows you to create realistic mock data without hardcoding values.

Syntax: <random:type> or <random:type:constraints>

Numeric Entities

Entity Description Example Output
<random:int> Random integer 42, 1337, 999
<random:int:between 5 and 100> Integer between 5 and 100 23, 67, 95
<random:int:min 5> Integer minimum 5 5, 42, 1000
<random:int:max 50> Integer maximum 50 10, 25, 50
<random:float> Random float 3.14, 42.56, 99.99
<random:float:between 5 and 100> Float between 5 and 100 23.45, 67.89

Date & Time Entities

Entity Description Example Output
<random:date> Random date 2024-03-15
<random:date:between today and tomorrow> Date within range 2024-12-16
<random:time> Random time 14:30:45

Text Entities

Entity Description Example Output
<random:name> Random person name John Doe, Jane Smith
<random:email> Random email [email protected]
<random:company> Random company Acme Corporation
<random:phone> Random phone +1-555-123-4567
<random:word> Random word lorem, ipsum
<random:guid> Random GUID/UUID 550e8400-e29b-41d4-a716-...

Request & Route Parameters

EchoMock can capture values from incoming requests and inject them into your responses, making your mocks more dynamic and realistic.

Entity Description Example
<route:paramName> Extract value from URL route parameters defined in endpoint pattern
Endpoint: /users/{userId}
Request: GET /users/123
Template: {"id": "<route:userId>"}
Output: {"id": "123"}
<params:fieldName> Extract value from request body/query parameters
Request body: {"name": "John"}
Template: {"message": "Hello <params:name>"}
Output: {"message": "Hello John"}

💡 Combining Route and Request Parameters

You can combine route parameters with request parameters for powerful dynamic responses:

Endpoint Pattern:

/users/{userId}/orders/{orderId}

Incoming Request:

POST /users/42/orders/999 {"status": "shipped", "priority": "high"}

Response Template:

{
  "userId": "<route:userId>",
  "orderId": "<route:orderId>",
  "status": "<params:status>",
  "priority": "<params:priority>",
  "processedAt": "<random:date>"
}

Actual Output:

{
  "userId": "42",
  "orderId": "999",
  "status": "shipped",
  "priority": "high",
  "processedAt": "2024-12-17 14:30:00"
}

Using Special Entities in Responses

Example 1: User Data

Request Template:

{
  "id": <random:int>,
  "name": "<random:name>",
  "email": "<random:email>",
  "phone": "<random:phone>",
  "company": "<random:company>"
}

Possible Output:

{
  "id": 42,
  "name": "John Doe",
  "email": "[email protected]",
  "phone": "+1-555-123-4567",
  "company": "Acme Corporation"
}

Example 2: Product Data

Request Template:

{
  "id": <random:guid>,
  "name": "Product <random:word>",
  "price": <random:float:between 10 and 100>,
  "stock": <random:int:between 0 and 500>,
  "rating": <random:float:between 1 and 5>
}

Possible Output:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Product lorem",
  "price": 45.67,
  "stock": 234,
  "rating": 4.2
}

Example 3: List of Items

{
  "users": [
    {
      "id": <random:int>,
      "name": "<random:name>",
      "email": "<random:email>"
    },
    {
      "id": <random:int>,
      "name": "<random:name>",
      "email": "<random:email>"
    },
    {
      "id": <random:int>,
      "name": "<random:name>",
      "email": "<random:email>"
    }
  ],
  "total": <random:int:between 50 and 200>
}

Note: Each special entity is evaluated independently, so you'll get different values for each occurrence.

Complete Request Examples

GET /users/{id} - Retrieve User

Method: GET
Status: 200
Accept: application/json
Delay: 500ms

Response:

{
  "id": <random:int>,
  "name": "<random:name>",
  "email": "<random:email>",
  "phone": "<random:phone>",
  "company": "<random:company>",
  "registeredAt": "<random:date>"
}

POST /users - Create User (Success)

Method: POST
Status: 201

Response:

{
  "id": <random:guid>,
  "message": "User created successfully",
  "createdAt": "<random:date>"
}

DELETE /users/{id} - Delete User (Error)

Method: DELETE
Status: 403

Response:

{
  "error": "Forbidden",
  "message": "You don't have permission to delete this user"
}

Best Practices

✓ Use Realistic Status Codes

Return appropriate HTTP status codes that match real API behavior

✓ Leverage Special Entities

Use special entities to create dynamic, realistic data instead of hardcoded values

✓ Add Delays for Testing

Use delays to test loading states, spinners, and timeout handling

✓ Create Multiple Scenarios

Create different request handlers for success, error, and edge cases

✓ Match Content Types

Ensure your response Content-Type matches the actual format of your response body

✓ Use AI Generation

Let AI generate realistic response structures to save time

Next Steps

Learn how to monitor requests and create new request handlers from the logs page!

Explore Logs & Monitoring →