Create and update resources

Creating resources are typically completed by using the collection URI, which is the same URI you use to query the resources. For example, the API call for creating assets is shown in the following example:

Post body:

After you create the asset, you get a response that contains a location header with the URI of the new asset. You can now use that location URI to fetch the new resource. Rather than doing a GET to fetch the resource, you may want the response of the create to contain the new resource. For that, you can add the request header properties. The properties header follows the syntax of the oslc.select clause. You can use that to fetch all properties, partial set of properties, related MBO attributes, formula properties etc (everything that you can do with the select clause).

Or

Using the properties header removes the need to do an extra GET for every create and update.

Now that an asset is created, you can update the asset. The following example shows how you can set a location and a description to the asset.

The URL has a rest id at the end of the collection URL. This URI is pointing to a member asset in the collection, which is why the rest id token is after the collection URI.

Note that we needed to fetch the URI of the mxasset resource in order to update it. The fetching of that URI can be done in two ways:

Although this is the prevalent design for URI interaction in REST paradigm, in some cases you may not have the URI and still need to update the asset based on other key information.

To add some child objects, the following API example adds two assetmeters to the new asset.

Post body:

An extra request header called patchtype is used with a value of MERGE. This instructs the server to match the child objects - like assetmeter with the existingassetmters for this asset. If a match is found, that assetmeter gets updates with the request assetmeter. If a match is not found, an assetmeter is created. This action is called the MERGE API. For example, if the asset to be updated has three existing assetmeters, and the request contained one existing assetmeter and one new assetmeter, that asset will be having 4 assetmeters with one newly created one and another updated assetmeter after the merge call.

To highlight the difference between a PATCH and MERGE call, you can run the same request without the patchtype header on another similar asset with three assetmeters. The server side creates a new assetmeter and update the existing assetmeter like the MERGE call. Unlike the MERGE call, the assetmeters that were not in the request are deleted. In this example, only two assetmeters (that are in the request) remains in the asset. Thus in a PATCH request, the server side deletes all child objects that are not in the request payload.

To update the child objects, the following example updates the assetmeter object to set the meter reading. Make sure that the np attributes, newreading and newreadingdate are included in the MXAPIASSET object structure.

Post body:

Notice that the primary keys of the assetmeter - metername and linearassetid for the meter update are included. Another option that the API allows is to use the href URI for the assetmeter instead of the primary keys, which is shown in the following example:

The following request below shows how to selectively delete a child object:

Note the use of child level actions (_action) to delete the assetmeter. You could have also used the child href instead of the primary keys as shown before. You could have also used the http DELETE method to delete the child object using the child object localuri URI.

Note the local URI for a child object (in Object structure) is something you can use to refer directly to the child object. You cannot do the same with the child href as that is an anchored URI. For example, you cannot use the child href for http DELETE.

By using the POST method with the _action child action, you can do a bulk delete of child objects, which you cannot do using the http DELETE method.