REST web services -Deploying and common issues


How to deploy?

Let`s use sample from RESTHost - Sample Solution - CRUD and File operations

To deploy and start a RESTHost svc:

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

  2. In the pop-up, configure your Linx Application 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 Application Server front end.

  5. Log into the Linx Application Server dashboard.

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

  7. The RESTHost svc 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 services dashboard.

Linx Designer and 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 RESTHost svc in the Linx Designer.

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


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 ...


This means that the Solution cannot compile due to there being 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 https://+:8022/service because this base URI is already in use.

The issue described above is due to there being more than a single RESTHost svc that is configured on the same Base URI.

The Base URI can only be used to host a single RESTHost svc, if you have multiple RESTHost svc 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 below error describes an invalid reference within the Solution, this means that at runtime the reference does not contain any value and thus cannot be used.

Exeception 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:

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:


There is an issue at the SetValue FNC in the OperationEvents_BeforeOperation EVT:

Technically, this is a valid reference (that 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 FNC as the whole $.Result object and then set the individual field values:

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:

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

Internal Server Error – No Log Entry

If you are receiving 500 (InternalServerError) 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 svc with regards to the Bearer Authentication scheme attached to an operation.

If you configure the RESTHost svc 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.

:green_book: Learn more about implementing Bearer authentication.