207 Multi-Status

Description

The 207 Multi-Status status code provides status information for multiple independent operations in a single response. This status code is primarily used in WebDAV (Web Distributed Authoring and Versioning) and other extensions to HTTP that need to return separate status information for multiple resources in a single request.

Unlike standard HTTP status codes that apply to the entire response, a 207 Multi-Status response contains an XML or JSON body that includes individual status information for each operation or resource that was part of the request. Each embedded response can have its own status code, headers, and response body.

This status code is particularly useful for batch operations, where a single request might involve actions on multiple resources, each with potentially different outcomes.

Syntax

The server responds with a 207 Multi-Status status and includes an XML or JSON body with individual status information:

HTTP/1.1 207 Multi-Status
Content-Type: application/xml
Content-Length: [length in bytes]

<?xml version="1.0" encoding="UTF-8"?>
<d:multistatus xmlns:d="DAV:">
  <d:response>
    <d:href>/resource1</d:href>
    <d:status>HTTP/1.1 200 OK</d:status>
  </d:response>
  <d:response>
    <d:href>/resource2</d:href>
    <d:status>HTTP/1.1 404 Not Found</d:status>
  </d:response>
  <!-- Additional responses as needed -->
</d:multistatus>

Examples

WebDAV PROPFIND Example

A client requests properties for multiple resources:

Client Request:

PROPFIND /collection/ HTTP/1.1
Host: webdav.example.org
Depth: 1
Content-Type: application/xml
Content-Length: 124

<?xml version="1.0" encoding="utf-8"?>
<propfind xmlns="DAV:">
  <prop>
    <displayname/>
    <getlastmodified/>
  </prop>
</propfind>

Server Response:

HTTP/1.1 207 Multi-Status
Content-Type: application/xml
Content-Length: 831

<?xml version="1.0" encoding="UTF-8"?>
<d:multistatus xmlns:d="DAV:">
  <d:response>
    <d:href>/collection/</d:href>
    <d:propstat>
      <d:prop>
        <d:displayname>Main Collection</d:displayname>
        <d:getlastmodified>Wed, 15 Jun 2023 12:30:15 GMT</d:getlastmodified>
      </d:prop>
      <d:status>HTTP/1.1 200 OK</d:status>
    </d:propstat>
  </d:response>
  <d:response>
    <d:href>/collection/document.docx</d:href>
    <d:propstat>
      <d:prop>
        <d:displayname>Project Document</d:displayname>
        <d:getlastmodified>Mon, 12 Jun 2023 09:45:22 GMT</d:getlastmodified>
      </d:prop>
      <d:status>HTTP/1.1 200 OK</d:status>
    </d:propstat>
  </d:response>
  <d:response>
    <d:href>/collection/image.jpg</d:href>
    <d:propstat>
      <d:prop>
        <d:displayname>Project Image</d:displayname>
        <d:getlastmodified>Tue, 13 Jun 2023 15:22:08 GMT</d:getlastmodified>
      </d:prop>
      <d:status>HTTP/1.1 200 OK</d:status>
    </d:propstat>
  </d:response>
</d:multistatus>

Batch API Operation Example

A client performs multiple operations in a single request:

Client Request:

POST /api/batch HTTP/1.1
Host: api.example.com
Content-Type: application/json
Content-Length: 358
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "operations": [
    {
      "method": "GET",
      "path": "/users/123",
      "id": "op1"
    },
    {
      "method": "POST",
      "path": "/products",
      "id": "op2",
      "body": {
        "name": "New Product",
        "price": 29.99
      }
    },
    {
      "method": "DELETE",
      "path": "/orders/456",
      "id": "op3"
    }
  ]
}

Server Response:

HTTP/1.1 207 Multi-Status
Content-Type: application/json
Content-Length: 782

{
  "results": [
    {
      "id": "op1",
      "status": 200,
      "body": {
        "id": 123,
        "name": "John Doe",
        "email": "[email protected]"
      }
    },
    {
      "id": "op2",
      "status": 201,
      "headers": {
        "Location": "/products/789"
      },
      "body": {
        "id": 789,
        "name": "New Product",
        "price": 29.99,
        "created_at": "2023-06-15T14:30:22Z"
      }
    },
    {
      "id": "op3",
      "status": 404,
      "body": {
        "error": "Order not found",
        "message": "The requested order with ID 456 does not exist"
      }
    }
  ]
}

Summary

The 207 Multi-Status status code is a powerful mechanism for handling complex, multi-resource operations in a single HTTP transaction. It provides detailed status information for each individual operation within a batch request, allowing clients to process successes and failures appropriately. While originally designed for WebDAV, this status code has found applications in modern RESTful APIs that support batch operations, allowing for more efficient communication by reducing the number of separate HTTP requests needed to perform multiple operations.