API operations

API operations are defined for certain API resources and represent actions performed on the API resource, like forward, register, discontinue etc. API operations might have many side effects, which in many cases makes them more suitable than regular PUT and POST requests. Some API operations might also trigger system jobs that can run for a while.

In the RamBase client API operations are typically presented in the context menu in the upper right corner of the different REX applications.

Get possible operations

All API operations can be found in the REST APIs documentation. It is also possible to retrieve the API operations by appending /api-operations to the URI.

will give a list of API operations for the specified sales order:

{
    "apiOperations": [
        {
            "apiOperationId": 100044,
            "status": 4,
            "name": "Delete all items",
            "apiOperationLink": "https://api.rambase.net/system/api/api-operations/100044?$db=TEM-NO&$format=json"
        },
        {
            "apiOperationId": 100059,
            "status": 4,
            "name": "Forward all items in sales order to existing sales order",
            "apiOperationLink": "https://api.rambase.net/system/api/api-operations/100059?$db=TEM-NO&$format=json"
        },
        {
            "apiOperationId": 100055,
            "status": 4,
            "name": "Register sales order",
            "apiOperationLink": "https://api.rambase.net/system/api/api-operations/100055?$db=TEM-NO&$format=json"
        },
        ...
    ]
}

Note that this is all API operations, but not all of them can actually be triggered for this sales order. Some API operations might only be available in certain statuses, when it exists items in the sales order and so on. Check out the check access request to learn how to find out which API operations can be triggered for this specific sales order.

Trigger an API operation

To trigger an API operation, you need to create an instance of the API operation. From the list above we found that the API operation 100055 needs to be triggered to register the sales order. More details about this specific API operation can be found here. In this case the API operation do not require any parameters, but others might require parameters to be specified in the request body. A POST request to the list of operation instances will trigger the API operation:

The response of the API request looks like this:

{
    "operationInstance": {
        "operationInstanceId": 2072948,
        "status": 7,
        "createdAt": "2020-06-29T17:14:00+02:00",
        "createdBy": {
            ...
        },
        "createdFor": {
            ...
        },
        "apiOperation": {
            "apiOperationId": 100055,
            "apiOperationLink": "https://api.rambase.net/system/api/api-operations/100055?&$format=json"
        },
        "objectReference": {
            ...
        },
        "error": {
            "message": "The sales order is already registered",
            "translatedMessage": "The sales order is already registered",
            "stackTrace": "AOP/100055 ApiImplementation.Exceptions.ForbiddenException\n",
            "errorMessage": {
                "errorMessageId": 101257,
                "errorMessageLink": "https://api.rambase.net/system/error-messages/101257?&$format=json"
            },
            "parameters": [],
            "innerErrors": []
        },
        "systemJob": {
            ...
        },
        "operationInstanceLink": "https://api.rambase.net/system/api/operation-instances/2072948?&$format=json"
    }
}

In this example the sales order was not registered because the sales order was already registered. Note that these API request will return HTTP 201 (OK) anyway, because the API operation instance was successfully created. The status field of the API operation instance is the key to find out how the API operation went:

• Status 9: The API operation went successful.
• Status 7: The API operation failed. The ErrorMessage element in the response should give details about what went wrong.
• Status 3: The API operation is still running. In these cases the SystemJob element in the response will have a reference to a specific system job still running to complete the operation. When the system job is completed the API operation instance will be updated with either status 7 or status 9.

Viewing history of API operations

All the created API operation instances for an API operation can be found by making a GET request to the same list as we make POST requests to: