We have a REST GET endpoint that returns device details. Something like this.

GET /device/{device_name}

Response:

{
  "device_type": "ABC",
  "device_name": "XYZ",
  ...
}

Requirement

There is a requirement to send back the device status as well. We need to do that without breaking existing contract.

My Solution

We will take an additional optional parameter to initiate the device status check and the status will be returned in the response. This will be completely optional field so won't break the existing contract.

My Dilemma

Since query parameter is generally used to filter the response, I am inclined to take this parameter in the request header.

I need your inputs in

1. Suggesting whether this should be a query or header parameter.
2. Naming convention. I am thinking of something like "x-check-device-status". (I know generally it is a noun. But in my case it is indicative of an action, that is to trigger a device status check)

Thanks in advance!

CodePudding user response：

I would not use a header for this, but rather just take this as an optional argument from the request body.

Regarding the naming, there is no need to go with the x- convention if you send it in the body. You could simply have boolean in a JSON, like so:

{
    "checkDeviceStatus": true
}

or

{
    "options": [
        {
            "checkDeviceStatus": true
        }
    ]
}

You of course also get to choose the default behaviour for this.

CodePudding user response：

Normally I would just return the following JSON:

{
  "device_type": "ABC",
  "device_name": "XYZ",
  ...
  "status": "operational"
}

If the clients are badly written, then this might break them. If this is a problem, then add a new endpoint:

GET /device/{device_name}?verbose=true
GET /device/{device_name}/status
GET /device/{device_name}/with-status
GET /device/{device_name}/with-status=true

Another option is versioning the API and do

GET api/v1/device/{device_name}
GET api/v2/device/{device_name}

I would not use header for this.