RESTHost - Get Started - Hello World!

[ronan]

RESTHost - Get Started

The below describes how to create a “Hello World!” REST API using the RESTHost ^svc.

Hello World

The web service will contain a single operation with the OperationID of HelloWorld which will be executed by a request to the path /helloworld.

The HelloWorld operation is configured to have a (200) OK response code and the response body will be a STR ^TYP .

The web service will be tested locally using service debugging.

Sample Solutions to aid understanding
Linx 5: HelloWorldAPI.lsoz (5.0 KB)
Linx 6: HelloWorldRESTHost6.zip (3.5 KB)

Add a RESTHost ^svc to the Solution

To add a RESTHost ^svc to a Solution, drag the RESTHost ^svc from the Plugins Panel (in the REST ^PLG section) into the Solution Explorer.

This will create a instance of a REST web service for you to build with.

Next, configure the Properties of the RESTHost ^svc like described in the following sections.

API Definition import

Import the below into the API Definition of the RESTHost ^svc:

openapi: 3.0.0
info:
  description: Linx Sample API
  version: 1.0.0
  title: Linx Sample API
paths:
  /helloworld:
    get:
      summary: Return the text 'Hello World!'
      description: Return the text 'Hello World!'
      operationId: HelloWorld
      responses:
        '200':
          description: OK (200)
          content:
            application/json:
              schema:
                type: string

This will create a HelloWorld operation in the Solution Explorer.

---

Linx Designer view:

---

Add operation logic

To add logic to the operation, click on the HelloWorld operation in the Solution Explorer , this will select the operation in the Design Canvas.

1. Add a STR ^TYP to the beginning of the operation by dragging it from the Plugins Panel onto the Design Canvas - this creates an instance of a STR ^TYP with the default Name of String.

2. Alter the initial Value of String to contain the text “Hello”.

3. Next, add another STR ^TYP to the operation , with the default Name of String1.

4. Alter the Value of String1 to the text “World”.

5. Add a SetValue ^FNC to the end of the operation, this is used to set the response body of the operation.

6. Reference $.Result as the Target Property of the SetValue ^FNC

7. To set the Source, select the Values Editor from the source drop down and populate the Response200 Property in the popup.
   

Here we will enter an expression which will combine both the STR ^TYP in the operation in the format of “Hello World!”.

8. In order to create such an expression, open up the expression editor (EX) in the Response200 Property of the SetValue ^FNC.

   Add the following expression:

   = String + " " + String1 + "!"

   This will combine the runtime values of the two STR ^TYP added earlier (String and String1).

   The result of this expression (“Hello World!”) will be returned in the response body when the operation completes.

---

Linx Designer view:

---

Debug service

In order to test the service out, you are able to debug the RESTHost ^svc. This will create a local instance of the service within the Linx Designer which you can then test calls on with your browser or Postman. This allows you to both test the configuration of your web service as well as debug the logic within them with real time data.

1. In order for service debugging to work on your local machine, configure the Base URI of the RESTHost ^svc to:

   http://localhost:8080/service
   

2. Next, right-click on the RESTHost ^svc in the Solution Explorer and click Debug.

   This will initiate the local instance of the service.

   In the Debug Output panel, the below message will appear:

   Compiling RESTHost...
   Compilation successful.
   Attaching debugger...
   Attached debugger successfully.
   Ready to debug. Click START to start debugging.
   

3. Next, click Start in the top menu bar.

   In the Debug Output panel of the Designer, the below message will appear:

   Starting service RESTHost...
   RESTHost service started.
   

   This indicates that the local service is active and test requests can be made.

Tip: In order to take a closer look at the runtime functioning of the operation, add a Breakpoint to the operation on one of the FNC. When the operation executes, the operation will pause at this FNC and you will be able to see the runtime values of the operation in the Debug Values panel. You will then be able to step through the operation’s logic step-by-step.

To add a breakpoint to the HelloWorld operation, right-click on the String TYP in the HelloWorld operation and select Add Breakpoint (See graphic below for more details).

4. To initiate the request flow, navigate to the below URL in a browser:

   http://localhost:8080/service/helloworld
   

   Make a Hello World! request

   In the Debug Output , a log indicating the request event containing the operation’s name and time of execution should be displayed.

   Starting service RESTHost...
   RESTHost service started.
   HelloWorld fired (12:33:27).
   

   Using Breakpoints:

   1. In the Designer, when a request is made, the debugger will pause on the String TYP in the HelloWorld operation which has a Breakpoint on it. If you look at the Debug Values panel , you will see the runtime values of String as “Hello”.
   2. Next, click the Step Over button in the top menu of the Debugger.
   3. The execution of logic will proceed to the next step which will expose the runtime value of String1 which is “World”.
   4. If you continue to click Step Over, the operation will complete.

The request should succeed and a (200) OK response is returned with the response body content of “Hello World!” displayed in the browser window.

Hello World!

---

Linx Designer view:

---

Congratulations!

You’ve created your first web service with Linx.

Next steps

Learn more about using REST web services in Linx.