Guidelines and Best Practices for ACVP Update Requests

General Update Formatting

Updates in the ACVTS are performed by issuing a "PUT" to the endpoint pertaining to the object to be updated. For example, to update the Organization object with ID 12345, a client would issue a PUT to /vendors/12345.

Per the ACVP Specification the body of the PUT request contains:

... any subset of the updateable properties. If a property is not included its value is not changed.
A null value for a property indicates the value should be removed

As such, if a user wishes to update the an organization object's name and nothing else, the body would consist only of:

[
    {"acvVersion": "{acvp-version}"},
    {
        "name": "New Organization Name, Inc."
    }
]

Please do not include any fields which are not to be updated.

As a rule of thumb, it may help to remember that: the server always seeks to make the state of the object in the database match the state of whatever is submitted. Any field included in the update is updated to whatever value is included, with null signifying removal.

Updating array fields

In line with the above rule of thumb, when updating an array field, the server will make the existing value match the value which is submitted.

As such, if a user wishes to remove a given object from an array field, the user need only submit the array field without the one they wish to remove. For example, if an object's addresses field contains the following:

{
    "addresses" : [
        { "url" : "/acvp/v1/vendors/12345/addresses/1"},
        { "url" : "/acvp/v1/vendors/12345/addresses/2"},
        { "url" : "/acvp/v1/vendors/12345/addresses/3"}
    ]
}

... and the user wishes to remove address 2 from association with this organization, their request, a PUT to /vendors/12345 will contain:

[
    {"acvVersion": "{acvp-version}"},
    {
        "addresses" : [
            { "url" : "/acvp/v1/vendors/12345/addresses/1"},
            { "url" : "/acvp/v1/vendors/12345/addresses/3"}
        ]
    }
]

Inline Object creation

Some endpoints support inline object creation, such as adding addresses to organizations. In these cases, if a user wishes to add an address to an organization for example, they need only provide the address object fully-populated in the array alongside the others which they wish to keep.

As mentioned earlier, the server always seeks to make the state of the object in the database match the state of whatever is submitted, so it will add the new address if one is given without a URL field.

For example, if an organization's address array consists of:

{
    "addresses" : [
        { "url" : "/acvp/v1/vendors/12345/addresses/1"},
        { "url" : "/acvp/v1/vendors/12345/addresses/2"}
    ]
}

... and a user wishes to add a new address without changing the others, they need only submit:

[
    {"acvVersion": "{acvp-version}"},
    {
        "addresses" : [
            { "url" : "/acvp/v1/vendors/12345/addresses/1"},
            { "url" : "/acvp/v1/vendors/12345/addresses/2"},
            {
                "street1" : "123 Main Street",
                "locality" : "Any Town",
                "region" : "AnyState",
                "country" : "USA",
                "postalCode" : "123456"
            }
        ]
    }
]

The resulting object would contain three addresses, the two existing ones and the new one.

Final Note: All the above logic can be combined to add and remove simultaneously, if desired. For example, a user could both omit a given array member and include a new one in the same request, and the existing one will be removed and the new one added in one request.