The possibility of returning HTTP status codes has been introduced in Endpoint responses. (HTTP Status Code: https://en.wikipedia.org/wiki/List_of_HTTP_status_codes).
The answers are grouped into five classes:
1xx: Informational - Request received, continuing process
2xx: Success - The action was successfully received, understood, and accepted
3xx: Redirection - Further action must be taken in order to complete the request
4xx: Client Error - The request contains bad syntax or cannot be fulfilled
5xx: Server Error - The server failed to fulfill an apparently valid request
All responses, whether in JSON, XML or LkString format, have a node called ERRORS. If this node has content, it means that an error has occurred and the response is returned with the HTTP status code 400. In other cases the response is returned with the HTTP status code 200.
In the case of Subroutine Endpoints, both in their Functions and SendCommand versions, in addition to controlling the content of the ERRORS node, there is the possibility of choosing an argument of the subroutine to be used as an HTTP status code. To do this, in these Endpoints, a parameter “arg_number_httpstatuscode” must be provided in the querystring which tells which argument of the subroutine will be used to get the HTTP status code. This parameter is optional. If an argument number is specified, this value will be validated to be greater than 0 and less than the number of arguments in the subroutine. If not, an HTTP 500 status code will be returned informing of the error. In other cases, if it is a valid HTTP status code, the response with that code will be returned. If it is not a valid HTTP status code, an HTTP status code 500 will be returned informing that it was not a valid code. If you do not indicate anything, the response code 200 will be sent.
In the case of Custom Endpoints, at the time of their creation through LinkarWS Manager, there is the possibility of specifying a value in the “Http Status Code Argument Number” property. This value will be used when Subroutine type templates are used in the content of the Custom Endpoint and will represent the position of the subroutine argument in which an HTTP status code can be found. That way if a valid HTTP status code is found in the subroutine response of the indicated argument, this code will be used to return the response.
This option is especially useful for returning 400 Error statuses to the client when the request does not comply with the business rules stipulated in the subroutine.
Find below an example with the SUB.DEMOLINKAR subroutine
SUBROUTINE SUB.DEMOLINKAR(SECONDS,DOWN,UPPER,HTTPSTATUSCODE)
IF NUM(SECONDS) THEN
SLEEP SECONDS
UPPER=OCONV(DOWN,"MCU")
HTTPSTATUSCODE=''
END ELSE
HTTPSTATUSCODE=400
END
RETURN
END
This subroutine will return Error 400 if the first argument is not a number.