Guide: OpenAPI 3 specification to Live API

Aug 31, 2022

User Guide: Go from Postman to Production


This guide will take you through the steps to design an API, build it, and deploy it to production. The process will take about 20 to 40 minutes to complete all steps. 
The project is to build a straightforward API to retrieve product data. You will be provided with the API specification, instructions for what tools to use, relevant scripts and all steps to get the API live.

Requirements:

Build an API that retrieves product information from a database and makes that data available as a JSON object. The API will have two endpoints:

  • Get All products – This endpoint will retrieve all products in the database table
  • Get Product By ID – This endpoint will retrieve the relevant product record based on an ID that is passed in.

WarningTo follow this guide, you will need:

  • An installed version of Postman 
  • An installed version of the Linx Designer
  • Access to a Linx Server (provided when downloading the Linx Designer) 

Table of contents

  1. Setup: API design and Postman setup  
  2. Using Linx: Setup and API service 
  3. Testing: Initial Postman test 
  4. Adding Logic: API backend logic 
  5. Testing: Testing the API
  6. Deployment: Putting the API into production
  7. Test: Testing the deployed solution

Let’s get started….

 

Setup: API Design and Postman Setup

 
IN POSTMAN:

Every API needs to be designed before it can be developed. In this section, you will import the OpenAPI definition into Postman.

1. In Postman, Create a workspace for your project.

2. Go to APIs and create a new API named Product. Use the OpenAPI 3.0 Schema type and YAML as the Schema Format.

OpenAPI 3.0 Schema

3. Define the API. This can be done by copying the below API schema:

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Product API
servers:
  - url: http://localhost:5000
paths:
  /products:
    get:
      summary: Get all products
      operationId: getAllProducts
      tags:
        - products
      responses:
        '200':
          description: List of products
          content:
            application/json:    
              schema:
                $ref: "#/components/schemas/Products"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /products/{productId}:
    get:
      summary: Get product by id
      operationId: getProductById
      tags:
        - products
      parameters:
        - name: productId
          in: path
          required: true
          description: The id of the product to retrieve
          schema:
            type: integer
      responses:
        '200':
          description: The product requested
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Product"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  schemas:
    Product:
      type: object
      required:
        - id
        - name
        - price
        - quantityInStock
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        price:
          type: number
        quantityInStock:
          type: integer
          format: int64
    Products:
      type: array
      items:
        $ref: "#/components/schemas/Product"
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string

Paste the copied definition into the Definition section of the API in Postman.  Ensure that the schema is set to YAML and click the save button:

API definiton in Postman

4. The API will be tested during development. To do so, create a Test Suite by clicking on the Add Test Suite button in the test section. Call it ‘ProductAPI’. A Test Suite is added in the Test section. Click on Add Test Suite.

5. You are now ready to build the API backend in Linx.

Using Linx: Setup and API Service

 

IN LINX

Now that the API definition is created and imported in Postman, we can create the API in Linx. This will be done via a REST Host service. 

About Linx
Linx is a general-purpose low-code platform for building and hosting backends. Developers design and debug solutions in a familiar procedural style using a drag-and-drop interface with access to 1000s of ready-made functions. Solutions are deployed with one click to servers running in the cloud or on-premise.

Further reading: Main concepts when using Linx

6.  In the Linx Designer, create a new solution.  Add the REST plugin by clicking on the ‘ADD PLUGINS’ button within the Plugins Panel. Add a RESTHost service to your solution by dragging the RESTHost component from the Plugins tab, onto the central canvas. If you do not see the RESTHost component expand the REST plugin by clicking on the arrow button.

Add REST Host

7. Paste the API Definition (YAML) into the API Definition property.

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Product API
servers:
  - url: http://localhost:5000
paths:
  /products:
    get:
      summary: Get all products
      operationId: getAllProducts
      tags:
        - products
      responses:
        '200':
          description: List of products
          content:
            application/json:    
              schema:
                $ref: "#/components/schemas/Products"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /products/{productId}:
    get:
      summary: Get product by id
      operationId: getProductById
      tags:
        - products
      parameters:
        - name: productId
          in: path
          required: true
          description: The id of the product to retrieve
          schema:
            type: integer
      responses:
        '200':
          description: The product requested
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Product"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  schemas:
    Product:
      type: object
      required:
        - id
        - name
        - price
        - quantityInStock
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        price:
          type: number
        quantityInStock:
          type: integer
          format: int64
    Products:
      type: array
      items:
        $ref: "#/components/schemas/Product"
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
API defintion

8. Set the Base URI property (under the API definition property) to http://localhost:5000. Save the Solution.

9. Debug the REST Host service. Do this by selecting the RESTHost, and then clicking on the Debug button. When the debugger is ready, click on the Start button. This will start the service in a locally hosted instance for testing.

Further reading: Debugging a Linx Solution 

Testing: Initial Postman Test

 

IN POSTMAN

You are now ready to test the API for the first time. Along with these initial tests, the automated test scripts will also be set up.

10. Run all the tests. If set up correctly, all tests will pass, but there will be no further detail to view.  This is because no tests have been set up. You will receive a “500 Internal Server Error” response from the API as no logic has been specified for the back-end process.

11. Add the tests to each of the methods. This can be done by clicking on the method and select the ‘test’ tab. The test functions have all been pre-created in this repo.- For products, add the test specified here:

const products = pm.response.json();
pm.test("More than 20 valid products", function () {
pm.expect(products.length).to.greaterThan(20, "Expected more than 20 items");
 products.forEach(x => {
    pm.expect(x.id).to.greaterThan(0, "Id should be > 0");
 })
});

For productid add the test specified here:

pm.test("Id is same as path param", function () {
   const path = pm.request.url.path;
   const pathParam = path[path.length-1];
  pm.expect(pm.response.json().id.toString()).to.equal(pathParam);
  });
Run tests in Postman

–  Run the tests again.  The tests will fail as no logic has been specified for the back-end process. You will still receive a “500 Internal Server Error” response from the API.

Test API

Adding Logic: API Backend Logic

 

IN LINX

In this section, you will add logic to events so that each endpoint will return the correct data once called.

12. For the getAllProducts event:

a) Add the Database Plugin from the Plugins panel.

b) Select the GetAllProducts event by clicking on it.

c) Add an ExecuteSQL function by dragging the ExecuteSQL function from the Plugins panel onto the central canvas:

ExecuteSQL

d) Create a new setting for the database connection string. Call the setting DB_Connection and set its value to

Server=postmandb.twenty57.net;Database=postmanTemplate;User Id=Guest_User;Password=DwVHXx!sVeA9x52Mhus6Vfg?;

You can use your own database. Ensure to add the connection string as per above. 

e) Set the connection string in the ExecuteSQL function to be the DB_Connection setting created above. It will then contain the value: $.Settings.DB_Connection

f) Set the Connection Type as ‘SQL Server’

g) Add the SQL below to that ExecuteSQL function:

SELECT 
     id
    ,name
    ,price
    ,quantityInStock
FROM dbo.Products;
Add SQL

Test the SQL script by clicking on the Test tab on the SQL box and executing the SQL. If successful you will be presented with a set of results.

h) Set the return options of the ExecuteSQL function to ‘List of rows’

Execute SQL function

i) Add a Return function to the event underneath the ExecuteSQL function.

ExecuteSQL

j) For the Value of the Return function, click on the edit button, then in the Response200 section, select ‘ExecuteSQL’ (the result of the SQL query from the function)

Set Value Function

Steps h to k set the response of the event to be the list of products returned by the ExecuteSQL function.

13. For the getProductByID event

a) Add an ExecuteSQL function

b) Set the connection to be the DB_Connection setting created above (in step 12). It will look like this: $.Settings.DB_Connection

c) Add the SQL below to that ExecuteSQL function:

SELECT 
    id
    ,name
    ,price
    ,quantityInStock
FROM dbo.Products
WHERE Id = @{$.Parameters.productId}

d) Set the return option of the ExecuteSQL function to only return the ‘First row’.

ExecuteSQL function

e) Add a Return function to the event that will set the response body to the ExecuteSQL result. To do this, click on the edit button for the Value, then in the Response200 section, select ‘ExecuteSQL’ (the result of the SQL query from the function)

Set value function

f) Save the solution

14. Debug the RESTHost Service

Testing: Testing the API

 

IN POSTMAN

In this section, you will test the API using Postman and ensure that endpoints return the data as expected.

15. Run all tests again. These should all pass.

Test API

If you are receiving an Internal Server Error for getProductById, ensure that a suitable parameter is being passed for the Product ID. Making this parameter 1 should work as there is a product with ID 1:

Postman test

A successful test will look like this:

succesful test

Once complete, deploy the solution to a Linx server where it will be hosted. 

Deployment: Putting the API into production

 

IN LINX

Now that the API is functioning as expected, it can be deployed to a server where it will be hosted and monitored. In this section, you will deploy the API. 

Before you can deploy the solution and call the API from the Linx Server, the BaseURI needs to be corrected to point to the servers URI:

16. In the Linx Designer, select the ProductAPI RESTHost service, change the BaseURI from ‘http://localhost:5000’ to ‘https://+:8080’

17. Set the API Documentation to be Swagger UI. This will allow the server to host Swagger UI documentation for our API.

 

api documentation

18. Rename the solution to ProductAPI. Do this by clicking on the solution in the solution explorer and then changing the name property then save the solution. This is important because it will reflect as such on the Linx Server with this name. Renaming it will make the solution easier to identify when you have more than one solution deployed. 

Rename solution

19. Now that the API is developed and final changes are made, it is time to deploy it to a server where it will be hosted.

As part of your initial sign-up, you should have received login credentials for a trial Linx server via email. If you have not received these details, please contact support

About the Linx Server:
The Server is a Windows Service that hosts and manages your Linx Solutions and web services. You can install Linx Server on the hardware of your choice (on-premise or cloud) with monitoring, metrics and logging as standard.

Further reading: Installing the Linx Server

To deploy your solution to the Linx Server, do the following:

a) In the Linx Designer, click Deploy
b) Set up the server using the credentials you have received
c) Click the Save button
d) Click the ‘DEPLOY & OPEN SERVER’
e) The solution will be deployed, and the server will be opened once the solution is deployed to the server. 

1-click deploy

These steps will only have to be taken the first time when setting up the server. After the server is set up with the Linx Designer, you can deploy by simply clicking on the  ‘DEPLOY & OPEN SERVER’ button. You can also use the ‘DEPLOY’ button if you already have the server open.

20. When you open the Server, and the solution is uploaded and ready to use, it should look like this:

Linx server

21. Click on the ProductAPI Solution, and then turn the RestHost service on:

Solution ON

22. Swagger documentation is hosted on the server and is accessible via any browser. You can access this by accessing the hosted API URL. The Hosted API URL is your server name ‘[my-domain].api.linx.twenty57.net‘. Add ‘/swagger’ to access the swagger documentation. 

The address will look something like this:

https://xxxxxx11.api.linx.twenty57.net/swagger

See the Swagger documentation hosted on the Linx server:

Swagger

Testing the Deployed Solution

You are now ready to test the hosted API

IN POSTMAN

In this section, you will test the hosted API using Postman and the automated tests that were set up.

23. Go to the ProductAPI collection and then select ‘Variables’

24. Change the ‘Current Value’ for baseUrl to be the URI for your server (same as in step 23). It will look something like the below with ‘xxxxxx11’ reflecting your server address:

https://xxxxxx11.api.linx.twenty57.net
API test

Ensure that you save your changes to the variable by clicking the save button. 

25. Call the products endpoint. The result will be a passed test.

Passed test

26. Call the get products by ID endpoint with ID 1. This should now result in a passed test

27. To test how the server monitors failures and errors, force a call with a value that will fail such as ‘-1’. This will force an internal server error as we have not specified logic to catch this kind of invalid parameter.

You can now head back over to the Linx server to view the monitoring and logging of events.

IN LINX SERVER

With testing concluded, check the monitoring and logging done on the server.

28. Open the solution to view the events and errors in the dashboard. A green indicator indicates a successful event, and a failure or error will be indicated by a red indicator:

Linx server

To view errors, click on the red indicator on the dashboard. Alternatively, click on Log to view displayed errors.

You have now:

  • Designed an API and setup tests in Postman
  • Developed an API and tested it via real-time debugging
  • Deployed the API to a server where it is hosted
  • Viewed hosted API documentation
  • Tested the deployed API

Now it is time to start building your own API.

Slack Need help? Join our Slack Channel