API Change Protocol - 20230315 - Blocked attribute

What we want to change:

Clear blocking process and add ability to block during creating and updating reservation

Why we want to change:

To make blocking of a reservation unified and as clear as is possible
To support blocking of a reservation not only during update operation but also during creating operation. So it is not neceserry to call API twice when caller wants create a new reservation and blocks it.

When we want to change:

Test environment: 12.3.2023

Production environemnt: 15.3.2023

Affected enpoints

POST /v2/reservation

PATCH /v2/reservation

Example of change:

When a caller wants to block (blocked:true) reservation instantly after creation (focus on a new blocked attribute on line 8 and filter for blocked inside query string on the first line and in response body line 6).

Request:

POST /parcel-lockers/v2/reservation?fields%5Breservation%5D=blocked

  "data": {
    "reservation": {
      "id": "test.res.1",
      "attributes": {
        "expirationDate": "2023-03-17T15:05:06.687Z",
        "blocked": true,
        "packages": [
          {
            "depth": 3.5,
            "height": 2.8,
            "width": 4.2,
            "barcode": "test.pkg.1"
          }
        ],
        "type": "NON_BINDING",
      },
      "relationships": {
        "box": {
          "id": 5,
        }
      }
    }
  }
}'

Response:

{
  "data": {
    "id": "test.res.1",
    "attributes": {
      "status": "RESERVED",
      "blocked": true,
      "createdAt": "2023-03-15T15:06:25.0824894Z",
      "expirationDate": "2023-03-17T15:05:06.687Z",
      "startReservationDate": null,
      "packages": [
        {
          "depth": 3.5,
          "height": 2.8,
          "width": 4.2,
          "barcode": "test.pkg.1",
          "packageState": "DISPATCHED"
        }
      ],
      "paymentData": null,
      "pin": "844840",
      "type": "NON_BINDING"
    },
    "relationships": {
      "box": {
        "id": 5,
        "pid": null
      }
    }
  },
  "metadata": null,
  "errors": null
}

When a caller wants to unblock (blocked:false) reservation later (the operation can be start based on some event - e.g. callback). Focus on response where same reservation like before is presented but has been updated (see line 6 with blocked attribute) and on query string with blocked requested attribute.

Request:

PATCH /parcel-lockers/v2/reservation?fields%5Breservation%5D=blocked

  "data": {
    "reservation": {
      "id": "test.res.1",
      "attributes": {
        "blocked": false
      }
    }
  }
}'

Response:

API specification diff:

https://github.com/AlzaBox/AlzaBox-API-Description/pull/7/files