Api Operations

Operations are used when the standard http GET, PUT, POST, DELETE are not enough. More exact, instead of updating or reading information about an object, we perform an operation on the object. An operation is always defined as a POST.

An operation is always bound to an Api Resource. The operations that are available for a specific resource are listed under a separate tab within the resource.

How to run an operation

An operation is always performed as a POST resource on an Uri with this format: https://api.rambase.net/{resourceUri}/api-operations/{operationId}/instances. The {resourceUri} should be replaced by the uri of the resource that the operation is connected to and the {operationId} should be replaced by the id of the operation you want to run.

For example, we can see that the resource https://api.rambase.net/documentation/tagview/?resourceno=325&version=21 has operations for approval and rejection of a service desk request. We can see that the operation to approve a service desk ticket has the operation id 100016. This means, to approve a service desk ticket, we perform a post to the uri https://api.rambase.net/collaboration/service-desk-requests/{serviceDeskRequestId}/api-operations/100016/instances. Of course we need to replace {serviceDeskRequestId} with the service desk ticket id we want to approve.

Results of an operation

The structure of the results of an operation is always the same. The exact format of it can be seen if you browse to an operation and go to the output tab, one example can be seen here: https://api.rambase.net/documentation/tagview/?resourceno=325&version=21&operationid=100016

The execution of an operation creates a new Api Operation Instance. The POST returns the identifier for the created Api Operation Instance (ApiOperationInstanceId). If the execution of the operation finishes quickly, the status of the result reveal if it ended with an error or if it went ok. The request may return before the operation has finished executing. This happens if the operation has a batch running in the background. In this case, there is a field called PercentDone that displays how far in the process the operation has come. This field can be seen when seeing information about an Api Operation Instance by running GET on the uri https://api.rambase.net/system/api/api-operations/{operationId}/instances/{instanceId}

Error handling

If an operation fails for some reason, the object status of the Api Operation Instance becomes 7. This is returned directly from the POST, but it can also be read from the GET resource https://api.rambase.net/system/api/api-operations/{operationId}/instances/{instanceId}. The result from the POST also contains an field called ErrorMessage with information about what went wrong.