RESTHost Guide - Returning data in the response body

ronan · October 14, 2020, 10:40am

Handling Responses

The explanations below are mostly for Linx5 users.

Feel free to contact support@linx.software and we'll assist.

All operations in a [RESTHost ^svc](https://linx.software/docs/reference/plugins/rest/content/resthost/) are set to have a default response $.Result.Data.HTTPContext.StatusCode of `(200) OK` with no-content as the ``response body`` regardless of the configuration.

This means that if you do not explicitly set the response to something else or throw an exception, a (200) OK response will be returned.

Below the follow sections are covered:

Using custom objects as response body
Setting custom responses (ResponseXXX)
Internal Error handling for responses

Using custom objects as responses

In the API Definition, you are able to define objects as both inputs and outputs.

When you have defined an object i.e. a User:

     User:
      type: object
      properties:
        email:
          type: string
        username:
          type: string
        id:
          type: string
        firstname:
          type: string
        lastname:
          type: string
      required:
        - email
        - username

And reference the object as a response body in the API Definition:

      responses:
        '200':
          description: OK (200)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

Linx will automatically import the specified object into the operation as the ResponseXXX response body. In this case the available response body will be Response200. To add additional response codes and objects, just amend them to the API Definition and they will be imported by Linx.

Tip: When setting these objects, always use the field editor in order to initiate the whole object, and set the individual fields all at once.

Setting custom responses (ResponseXXX)

The logic of an operation’s response works as follows:

At the beginning of an operation, the response $.Result.Data.HTTPContext.StatusCode is set to have a default status code of (200) OK.

If the outgoing $.Result.Data.HTTPContext.StatusCode is not altered during the operation, then the default Response200 body will be returned with no-content .

If you want to return a different status code, let's say a (404) Not found if a record doesn't exist or a (201) Created when you add a user, then you need to set the $.Result.Data.HTTPContext.StatusCode to the appropriate code first in order to initiate the correct response object.

However, in order to set the Output.Data.HTTPContext.StatusCode property you must set (initiate) the entire Output.Data.HTTPContext

Using a SetValue ^FNC :

Set the Target property as $.Result.Data.HTTPContext
Use the field editor to set the $.Result.Data.HTTPContext.StatusCode property:
Once you've initiated the respective response object, you can then set the content of the response by referencing $.Result.Data.ResponseXXX

So, for instance, if you want to return a (404) Not Found response with the errors included, you first add the response as part of the API Definition like below:

...
  /helloworld:
    get:
      summary: Return the text 'Hello World!'
      description: Return the text 'Hello World!'
      operationId: HelloWorld
      security:
      - Token: []
      responses:
        '200':
          description: OK (200)
          content:
            application/json:
              schema:
                 $ref: '#/components/schemas/User'
        '404':
          description: Not Found (404)
          content:
            application/json:
              schema:
                 $ref: '#/components/schemas/ErrorResponse'

...

components:   
      schemas:
...
        ErrorResponse:
          type: object
          properties:
            summary:
              type: string
            error:
              type: string

Then, using a SetValue ^FNC, reference the $.Result.Data.HTTPContext as the Target and then use the field editor to set the StatusCode to 404.

Using another SetValue ^FNC, reference the $.Result.Data.Response404 as the Target and then using the field editor the individual fields of the response are set as the Source.

The Response404 will be like below:

{
   "summary":"Not Found",
   "error":"Customer ID does not exist."
}

Linx Designer View

Internal error handling

All operations are set to have a default response HTTP status code of (200) OK with no-content as the body regardless of the configuration.

This means that if you do not explicitly set the response to something else or throw an exception, a (200) OK response will be returned.

In terms of handling exceptions:

Using a TryCatch ^FNC you are able to execute logic and ‘catch’ any error that occurs.

You are then able to internally handle any exceptions that may occur by using custom logic to do additional processing with this information such as logging or sending an email notifications.
In cases of internal/custom validation errors, you are also able to return custom error codes such as 404 or 422 for custom errors such as 'Invalid email address'. This is done by setting the custom response.
```
{
   "summary":"Invalid fields",
   "errors":[
      "Username: Already exists [Linx]"
   ]
}
```
If an unhandled exception is thrown or an explicit exception is thrown in any of the request flow stages, then a (500) Internal Server Error will be returned.
In order to explicitly throw an exception anywhere in an event, operation or process, add a ThrowException ^FNC.

This will cause a critical exception to be thrown with the below response:
```
500 (Internal Server Error)
```
You have the option of including or omitting the actual stack trace errors from the response by altering the RESTHost ^svc Return server errors Property.

In this case, a response containing the stack trace of the error will also be included in the response: