REST endpoint, return something other than 204 or httpError?

Developer Programs Writing SmartApps
1

REST best practice is to use specific http response codes for specific conditions. httpError() shows up prominently in several REST examples, and works great for 4xx and 5xx codes. But is there an equivalent for returning a specific non-error status (e.g. 2xx, 3xx)? Doing nothing at all returns a code 204 to the client, which may or may not be accurate. You CAN do "httpError(200, “It worked!”), and the client DOES get that response, but also raises it as an exception to the SmartThings logger, presumably because httpError is for… errors.

Shouldn’t there be a httpResponse() or httpStatus() ? Are these methods adopted from a standard library somewhere for which documentation DOES exist? :wink:

2 Likes
2

If your endpoint method returns content, the status code should automatically change to a 200. And if your endpoint method does not return a message body, the system will automatically return a 204.

Which specific HTTP Status Codes are you looking for?

3

I could be missing something. What does “return[s] a message body” mean? If return a string, I do not see it at the client, and the code is still 204.

4

How are you returning a string? Can you share some code?

Here’s a quick (untested) example showing what I mean… In the example, we will setup preferences to allow the user to select some switches, then map an HTTP endpoint to allow a GET request which will call a function that loops through the list of switches getting information about each and returns JSON content with information about the switches.

preferences {
    section("Allow MyCoolApp to Get Switch Info...") {
        input "switches", "capability.switch", title: "Which Switches?", multiple: true, required: false
    }
}

mappings {
    //-----Device Endpoints-------
    path("/switches") {
        action: [
                GET: "listSwitches"
        ]
    }
}


//-------------Device Actions----------------
def listSwitches() {
    switches.collect {
        deviceItem(it)
    }
}

//example method to build a structured data element (ultimately for a JSON response)
private deviceItem(device) {
    [
            id: device.id,
            label: device.displayName,
            currentStates: device.currentStates,
    ]
}

Since we are (implicitly) returning content, the system will respond with a 200 in this case. If we added a PUT method to allow the user to modify the device and in that case we only needed to return the success/failure (eg. no data/content in the response) then we would catch any failures and return them with an httpError(code, message) and by default the successful executions would return a 204 response (all OK, but no content to return).