Calling Modify APIs

Access Modify APIs with PATCH HTTP requests. Modify APIs update the information of existing resources.

REST Modify requests use the following types of APIs depending on the Name of the resource that is specified:

manageName (with Operation=Modify)
manageNameHierarchy (with Operation=Modify)
modifyName
modifyNameHierarchy
changeName
changeNameHierarchy

For example, Modify requests for orders use changeOrder, and Modify requests for organizations use manageOrganizationHierarchy. To see the complete list of resources and APIs, view the REST Javadoc files.

Request format

Use the following HTTP request format to call Modify APIs:

PATCH http://host:port/contextRoot/restapi/Name/id

Name is the type of resource to be modified, and id is the value of its primary key, NameKey.

The following example shows a request to modify an order with an OrderKey equal to 12345:

PATCH http://host:port/contextRoot/restapi/order/12345

You can make Modify calls with PUT if you set servlet.put.enabled to true in the xapirest.properties file.

Create-Or-Modify

You can use the "manage" APIs to update a resource if it exists or create the resource if it does not exist in a single Create-Or-Modify request. To Create-Or-Modify through REST, submit a PATCH to the Name of the resource collection and pass a document that describes the resource in the request body.

PATCH http://host:port/contextRoot/restapi/Name

The Create-Or-Modify feature is only compatible with resource types that use "manage" APIs. For example, items use manageItem, and organizations use manageOrganizationHierarchy, so you are able to Create-Or-Modify items and organizations with PATCH. Refer to the Javadoc files to see whether a resource type uses "manage" APIs.