Executing Commands via the WebAPI

Whereas API objects represent entities with many fields of data, commands represent actions or requests for a single piece of data that does not map to any businessobject. Commands are used to retrieve information or modify data. For example to calculate the price of a product under certain circumstances (informational) or process a sales order (modify).

Executing Commands

Commands are executed in the same way business objects are created, via HTTP POST operations. Visit the WebAPI help page for a list of available commands.

Arguments are passed in a slightly different way that is usual for business objects. Instead of using an url where the parameter values are seperated by a slash, the arguments are passed via a querysting. This better suites the purpose of commands because a command does not represent a path to a resource, but an action with arguments.

The following call will retrieve the specprice for the given criteria. This command only calculates a price based on its input and does not modify any state.

        
    POST api/MVL01001/CalcSpecPriceCommand?customerId=1001&productId=80.100¤cyId=USD&quantity=1&orderDate=1-1-2014&vatIncluded=true
	    
    

The next command processes an order which modify state on the server.

        
    POST api/MVL01001/ProcessOrderCommand?journalId=V&fiscalYear=2014&periodNumber=1&invoiceDate=1-1-2014&orderId=20140015&journalTransaction=1
	    
    

If a command has only one method, the name of the method is omitted in the url, some commands have more than one method, in that case the name of the method appears after the name of the command. Like so:

        
    POST api/MVL01001/ProgramRightsCommand/CanUserEditInProgram?programNumber=31225
    POST api/MVL01001/ProgramRightsCommand/CanUserStartProgram?programNumber=31225
	    
    

Reading the result

When a command is executed the server sends a result representing the command, typically consisting of one or more properties describing the result of the command. In some cases the input values of the command are also returned. The result of the spec price command as shown in the first example is as follows.

            
    POST api/MVL01001/CalcSpecPriceCommand?customerId=1001&productId=80.100¤cyId=USD&quantity=1&orderDate=1-1-2014&vatIncluded=true

    {
        "discount": 0.0,
        "price": 90.75,
        "stockTransferPrice": 35.0
    }
	        
        

Some commands can fail when executing, due to invalid arguments or other constraints that were violated or have other special argument checking. These commands often expose and Error property that indicates why the command has did not successfully execute. Such a response might look like this:

            
    POST api/MVL01001/ApproveInvoicePaymentCommand?invoiceId=20140015&approverId=2

    {
        "approved": false,
        "approverId": "2",
        "error": "Cannot approve SupplierIdByInvoiceId, because the setting CompanyDetails.ApproveSupplierIdByInvoiceId is set as False.",
        "invoiceId": "20140015"
    }