RESTHost - Handling responses

Warning:

The steps provided in this explanation are based on Linx before release 6.4.0.

In there is a Return function in the Linx plugin that must be used for setting the value of a function's result. The SetValue function and $Result cannot be used for this purpose anymore.

Go for details of the Return function.

All operations in a RESTHost service 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.

Using Custom Objects as Response Body

In the API Definition, you can define objects as both inputs and outputs.

When you have defined an object, such as 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 function:

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 function, reference the $.Result.Data.HTTPContext as the Target and then use the field editor to set the StatusCode to 404.

Using another SetValue function, 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 function, 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 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 function.

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 service Return server errors Property.

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

Warning:

The steps provided in this explanation are based on Linx before release 6.4.0.

In Linx 6.4.0 and higher there is a Return function in the Linx plugin that must be used for setting the value of a function's result. The SetValue function and $.Result cannot be used for this purpose anymore.

Other Guides for Hosting a REST API

Sample

Last updated 1 month ago