Composite

Send a Composite Request

Submit a sequence of request in one action. The base composite request fields are listed below.

Fields Required Description
all_or_none No Boolean that controls the transaction semantics of the request. When true all requests will be made in a single transaction, if one fails the rest will fail as well and any completed requests will be rolled back. When false the system will attempt to complete all requests. Ones that fail will be marked as such, the rest will be committed. Defaults to true.
composite_request Yes A list of dictionaries representing the requests being made. See the next section for details on how each individual request dictionary should be formed.

Individual Request Definition

Each request in the sequence should contain the folowing:

Fields Required Description
method Yes String representing the HTTP method of the request. Should be one of GET, POST, PATCH or DELETE.
path Yes The path to which the request is being made. Should be a valid SD Elements API path. May contain references to prevoius requests. To use a reference, wrap the reference ID as such: @{ref1}.
reference_id Yes Reference ID of the request. May be used in subsequent requests.
body No Body of the request. Should contain valid JSON. Specifics of the body will be defined by the relevent SD Elements API endpoint documentation match the method and path combination specified in previous parameters.

Some extra notes on reference IDs:

  • Each reference ID must be unique within the scope of a single composite API request.
  • When dereferencing, the @{ref} syntax must not contain any white space.
  • Each use of the @{ref} syntax will attempt to be filled in, and if no matching reference is found the request will fail. There is currently no way to escape the syntax. Should you need to make a request with this syntax in the body please use a regular API request.
  • The reference syntax can include nested reference and array access. For example, @{ref.results[0].name} is valid sytax, it will find the response body of the ref request, then look for a results property inside it, take its first item and use its name property as the final value. Should results not be an array or name not exist then the request will fail. Also the ref itself does not support array access, so @{ref[0].name} is invalid.
POST /api/v2/composite/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "all_or_none": true,
    "composite_request": [
        {
            "method": "POST",
            "path": "/api/v2/business-units/",
            "reference_id": "bu_ref",
            "body": {
                "name": "New Business Unit 4"
            }
        },
        {
            "method": "GET",
            "path": "/api/v2/applications/?name=Base App",
            "reference_id": "app_ref"
        },
        {
            "method": "POST",
            "path": "/api/v2/applications/",
            "reference_id": "new_app_ref",
            "body": {
                "name": "@{app_ref.results[0].name} (Clone)",
                "business_unit": "@{bu_ref.id}"
            }
        }
    ]
}

HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "composite_response": [
        {
            "reference_id": "bu_ref",
            "http_status_code": 201,
            "http_headers": {
                "Content-Type": "application/json",
                "Allow": "GET, POST, HEAD, OPTIONS",
                "X-Debug-Query-Count": "19"
            },
            "body": {
                "all_users": false,
                "created": "2024-07-12T16:44:03.614808-04:00",
                "default_groups": [],
                "default_users": [],
                "groups": [],
                "name": "New Business Unit",
                "slug": "new-business-unit",
                "id": 9,
                "updated": "2024-07-12T16:44:03.614816-04:00",
                "users": [],
                "persist_phases": false,
                "default_risk_policy": null
            }
        },
        {
            "reference_id": "app_ref",
            "http_status_code": 200,
            "http_headers": {
                "Content-Type": "application/json",
                "Allow": "GET, POST, HEAD, OPTIONS",
                "X-Debug-Query-Count": "1"
            },
            "body": {
                "results": [
                    {
                        "id": 1,
                        "business_unit": {
                            "id": 1,
                            "name": "Old Business Unit",
                            "slug": "old-business-unit"
                        },
                        "name": "Base App",
                        "created": "2024-01-26T10:20:32.535977-05:00",
                        "updated": "2024-07-09T13:09:55.987148-04:00",
                        "archived": false,
                        "priority": "0-none",
                        "slug": "base-app",
                        "custom_attributes": {},
                        "tags": []
                    }
                ]
            }
        },
        {
            "reference_id": "new_app_ref",
            "http_status_code": 201,
            "http_headers": {
                "Content-Type": "application/json",
                "Allow": "GET, POST, HEAD, OPTIONS",
                "X-Debug-Query-Count": "11"
            },
            "body": {
                "id": 5,
                "business_unit": 9,
                "name": "Base App (Clone)",
                "created": "2024-07-12T16:44:03.674439-04:00",
                "updated": "2024-07-12T16:44:03.670264-04:00",
                "archived": false,
                "priority": "0-none",
                "slug": "base-app-clone",
                "custom_attributes": {},
                "tags": []
            }
        }
    ]
}

results matching ""

    No results matching ""