Composite operations (multi-resource) in Rest API

Introduction

Composite operations let you do many related tasks in one go. This saves time and keeps things simple.

When you want to create a user and their profile together.

When updating multiple related records at once, like order and payment.

When deleting a group of connected resources safely.

When you want to reduce the number of calls to the server.

When you want to keep data consistent across several resources.

Syntax

Rest API

POST /composite-operation
{
  "operations": [
    {"method": "POST", "path": "/users", "body": {"name": "Alice"}},
    {"method": "POST", "path": "/profiles", "body": {"userId": "${results[0].body.id}", "bio": "Hello!"}}
  ]
}

The request is usually a POST to a special endpoint like /composite-operation.

Each operation inside has a method, path, and optional body.

Examples

Create a task and then a reminder linked to that task.

Rest API

POST /composite-operation
{
  "operations": [
    {"method": "POST", "path": "/tasks", "body": {"title": "Buy milk"}},
    {"method": "POST", "path": "/reminders", "body": {"taskId": "${results[0].body.id}", "time": "9am"}}
  ]
}

Delete an order and its payment in one request.

Rest API

POST /composite-operation
{
  "operations": [
    {"method": "DELETE", "path": "/orders/123"},
    {"method": "DELETE", "path": "/payments/456"}
  ]
}

Sample Program

This example shows creating a user and their profile together. The profile uses the user ID from the first operation.

Rest API

POST /composite-operation
{
  "operations": [
    {"method": "POST", "path": "/users", "body": {"name": "Bob"}},
    {"method": "POST", "path": "/profiles", "body": {"userId": "${results[0].body.id}", "bio": "I love coding."}}
  ]
}

Response:
{
  "results": [
    {"status": 201, "body": {"id": "u123", "name": "Bob"}},
    {"status": 201, "body": {"id": "p456", "userId": "u123", "bio": "I love coding."}}
  ]
}

Important Notes

Composite operations help keep related changes together, so you don't have to worry about partial updates.

Make sure the API supports referencing results from earlier operations, like using ${results[0].body.id}.

Check the response carefully to handle errors in any part of the composite request.

Summary

Composite operations combine multiple API calls into one request.

This saves time and keeps data changes consistent.

Use them when working with related resources that depend on each other.