What is the Command pattern?

In Allegro REST API there are resources that correspond to typical CRUD operations Create, Read, Update, Delete), which are mapped to relevant methods HTTP POST, GET, PUT, DELETE.

In addition to these resources, which are semantically simple, there are also resources referring to complex operations or certain actions with reference to an object (e.g. offer, transaction, user, etc.).

A request directed to such resource may result in the performance of a few operations on Allegro and/or making changes to object attributes, or invokes certain business consequences for the Allegro platform (including integrated systems) and users participating in a process (listing an offer, shopping transaction). Sample operations include: “suspend and resume an offer”, “change Buy it Now price in active offer”.

In the case of such operations, the Command programming pattern was used to execute REST API.

Command is a behavioral design pattern, used to encapsulate actions to be performed and their parameters. It defines a command as an object sent from the client to the recipient, which allows for such functionalities as: command queuing, history checking (even with “undo” operation), etc.

For Allegro REST API, the structure of these resources is as follows:

Request:

 PUT /business-resource/{resource-identifier}/{command-type}-commands/{uuid-command-identifier

Body:

 {
    // input data relevant for the command, e.g.:
    “input”: {
        "buyNowPrice": {
            "amount": "122",
            "currency": "PLN"
         }
    }
 }

Response:

 201 Created
 {
    “id”: “9b84e1bc-5341-45e7-837e-4250720e606f”,
    “input”: {
        "buyNowPrice": {
            "amount": "122",
            "currency": "PLN"
         }
    },
    “output”: {
        "status" : "RUNNING",
        "errors" : []
        // other return data relevant for the command
    }
 }

For example, a resource enabling the execution of the price change operation is:

 PUT /offers/12345/change-price-commands/84c16171-233a-42de-8115-1f1235c8bc0f

In executing a request for such resource, you should add the price change command identifier 84c16171-233a-42de-8115-1f1235c8bc0f, to the set of actions to be performed on the offer indicated by the identifier = 12345.

You should remember that we use the http PUT method instead of the POST method for these resources, which means that it is the client to indicate (send) an identifier for the command.

To ensure that the command identifier sent by the client in the request is unique, it is necessary to provide identifiers in the UUID standard.

Application

What results gives the application of this pattern?

  • a standardise way to declare the performance of the operation - we receive a unified API and any complex operations are performed on resources executed in the same way - there is an action to be performed and parameters;

  • a standard mechanism to track asynchronous operation status - in addition to a resource called by the http PUT method there may be a resource called by the GET method to return the current command processing status;

  • an operation to be performed in an idempotent way - the PUT method is idempotent, which means that each subsequent request results in the updating of the same resource and does not change the result.

Sources