REST-deployment

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.

Go here for details of the Return function.

How to Deploy

To deploy and start a RESTHost service:

  1. In the Linx Designer, click the Deploy button in the top menu.

  2. In the pop-up, configure your Linx Server’s Server URL, User, and Password fields.

  3. Click Deploy & Open Server.

  4. Once the Solution has been uploaded and started, you will automatically be navigated to the Linx Server front end.

  5. Log into the Linx Server dashboard.

  6. Navigate into the Solution services, find the RESTHost service that you created, and turn it ON.

  7. The RESTHost service is now activated.

Once this is done, the service will monitor for incoming requests and send responses. Incoming requests, as well as the subsequent results of the operations, are logged and can be viewed on the service dashboard.

Linx Designer and Server View:

Server View

Common Deployment Issues

Accessing ‘localhost’ Externally

A common issue is that the Base URI prefix is set to “localhost,” i.e., http://localhost:8022/service when debugging the RESTHost service in the Linx Designer.

When deploying to the Linx Server, to use the local host of the server as the Base URI, use the + character like below:

https://+:8022/service/

This wildcard character (+) will “grab” the current local hostname to generate the Base URI.

Start Solution Failed

If you see the upload dialog like below, this means that there is a fatal error in the application, and the application cannot compile (invalid references, incomplete expressions, etc.).

Error on server: StartSolution failed...

Start Failed

This means that the Solution cannot compile due to a design error in terms of logic. To view the issue, click on the more option and address the specific error.

Base URI Conflict

The prefix 'http://+:8080/service/' is already registered.

Cannot start REST service on base URI http://+:8022/service because this base URI is already in use.

The issue described above is due to there being more than one RESTHost service configured on the same Base URI.

The Base URI can only be used to host a single RESTHost service. If you have multiple RESTHost services in your solution, ensure that they are using unique Base URIs. If an active service shares the same Base URI as a newly deployed Solution, the existing service will take preference.

Invalid Object Reference

The error described below details an invalid reference within the Solution, meaning that at runtime the reference does not contain any value and thus cannot be used.

Exception at SetValue: Object reference not set to an instance of an object.

Normally, in the Designer, if you have invalid references, you will be shown them:

Invalid Object

However, certain properties may have valid references in the Designer, but at runtime, the values contained in these references are NULL.

Typically, this occurs in operations when individual child fields are set before the whole parent object is initiated.

For example:

Capture

There is an issue at the SetValue function in the OperationEvents_BeforeOperation event:

Issue

Technically, this is a valid reference (which is why there are no error validations visible in the Designer); however, at runtime, an error is thrown because the parent $.Result object has not been initiated. In this case, you would set the Target of the SetValue function as the whole $.Result object and then set the individual field values:

Set Target

Server Runtime Errors

If an unhandled error occurs during runtime on the Server, such as an error with a request, it will appear on the service dashboard in red:

Service Dashboard

You can view a detailed stack trace of the error by navigating to the Log option on the left panel.

Service Logs

Internal Server Error – No Log Entry

If you are receiving 500 (Internal Server Error) responses when making a request to a Linx web service and there is nothing in the Server Log, this indicates that there is an issue with the authentication setup of the RESTHost service concerning the Bearer Authentication scheme attached to an operation.

If you configure the RESTHost service to return server errors as True, then when you make the request again, the error will be included in the response.

Response received ... Response Code: 500 (InternalServerError) Response Body: ("ClassName":"System.ArgumentException","Message":"IDX10703: Cannot create symmetric security key. Key length is zero."} ...

If the response is similar to the above, please ensure that you have configured the Auth config correctly by referencing the signing key used in the generation of the JWT Tokens.

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.

Go here for details of the Return function.

Other Guides for Hosting a REST API

Sample

View our sample solution on GitHub.

Last updated