RESTHost - Handling responses

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.

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.

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:

1. Set the Target property as $.Result.Data.HTTPContext
2. Use the field editor to set the $.Result.Data.HTTPContext.StatusCode property
3. 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 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 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:

Other guides for hosting a REST API

RESTHost Overview Guide

Get Started - Hello World

Before and After operation events

Working with inputs

Securing your API

Deploying and common issues

Generating API documentation

Sample solution: CRUD and file operations

Sample

View our sample solution on GitHub.