Deliver an API, running in production, in under 30-minutes 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: – This endpoint will retrieve all products in the database Get All products – This endpoint will retrieve the relevant product record based on an ID that is passed in. Get Product By ID To follow this guide you will need: An installed version of the Linx Designer Access to a Linx Server (provided when downloading the ) Linx Designer 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 Let’s get started… Setup: Setup the API Service Linx will be used to create and host the API. As part of Linx, there is a REST plugin that allows you to host and consume REST APIs. For this guide, you will create an API using the service. This service will allow you to create an API via a wizard. Simple REST Host In the Linx Designer, create a new solution. Add the by clicking on the ‘ADD PLUGINS’ button within the Plugins Panel. 1. REST plugin Add a service to your solution by dragging the SimpleRESTHost component from the Plugins tab, onto the central canvas. 2. SimpleRESTHost Set the Base URI property (under the API definition property) to http://localhost:5000. Save the Solution. 3. To create the events that will act as endpoints, you first need to make the custom type that will be returned. This custom type will be returned as a JSON object when the endpoint is called. To create this custom type click on the Solution ribbon, and click on the option. 4. Import Type Paste the below JSON into the dialogue box. Name the type of then click the create button Product [ { "id": 0, "name": "string", "price": 0, "quantityInStock": 0 } ] You can now create the events that will function as the endpoints of the API. Select the SimpleRESTHost, then click on the ellipses next to the Operations setting. 5. To create the event do the following: 6. GetAllProcucts I. A default operation will exist in the operation list. Change the name to GetAllProcucts ii. Set the path to be /products iii. Set the response body to be a list of the type that was created in step 3. To do this click on the dropdown on the response body, select List, then click on the edit button and select under the solution section Product Product To create the event do the following 7. GetProductByID i. On the operation wizard, click on the ADD OPERATION Button ii. Set the name to GetProductByID iii. Set the path to be /productByID iv. Create a Query String parameter by clicking on the ellipses and then adding in an id parameter as a string v. Set the response body to the Product type that was created. vi. Save the operations Once successfully saved you will see the operations created under the SimpleRESTHost. The next part will focus on adding logic to retrieve the data from a database so that it can be returned as a response when the endpoints are called. Building: Add logic to the events In this section, you will add logic to events so that each endpoint will return the expected data once called. For the event: 8. getAllProducts i. Add the Plugin from the Plugins panel. Database ii. Select the event by clicking on it. GetAllProducts iii. Add an function by dragging the ExecuteSQL function from the Plugins panel onto the central canvas: Create ExecuteSQL iv. Create a new for the database connection string. A setting can be created by clicking on the Settings icon and then adding the new setting to the grid. Call the setting and set its value to: setting DB_Connection 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. v. Set the connection string in the ExecuteSQL function to the setting created above. It will then contain the value: DB_Connection $.Settings.DB_Connection vi. Add the below to that ExecuteSQL function: SQL SELECT id ,name ,price ,quantityInStock FROM dbo.Products; 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. vii. Set the return options of the function to ‘List of rows’ ExecuteSQL viii. Add a function to the event underneath the function. Return ExecuteSQL ix. For the Value of the Return function, click on the edit button, then in the ResponseBody section, select ‘ExecuteSQL’ (the result of the SQL query from the function) Steps VI to IX set the response of the event to be the list of products returned by the ExecuteSQL function. For the event: 9. GetProductByID i. Add an ExecuteSQL function ii. Set the connection to be the DB_Connection setting created above (in step 13). It will look something like this: $.Settings.DB_Connection iii. Add the below to that ExecuteSQL function: SQL SELECT id ,name ,price ,quantityInStock FROM dbo.Products WHERE Id = @{$.Parameters.id} iv. Set the return option of the ExecuteSQL function to only return the ‘First row’. v. 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 ResponseBody section, select ‘ExecuteSQL’ (the result of the SQL query from the function). Save the solution. Debugging: Ensure the events work In this section, you will debug the API to test it and ensure that it is working as expected. the Simple REST Host service. Do this by selecting the SimpleRESTHost, 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. When done the debug output should have a message that reads: ‘SimpleRESTHost service started.’ 10. Debug Test the event. Do this by calling the below URL in any browser when the SimpleRESTHost service has started in debug mode: 11. getAllProducts http://localhost:5000/products Note that the response body is a JSON object list that contains all products in the database table. Test the event. Do this by calling the below URL in any browser when the SimpleRESTHost service has started in debug mode: 12. GetProductByID http://localhost:5000/productByID?id=1 (calling the endpoint in a browser) To stop debugging you can click on the Stop button and then click on the EXIT DEBUGGING button. Deployment: Get the API on a server 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: In the Linx Designer, select the ProductAPI RESTHost service, change the BaseURI from to 13. http://localhost:5000 https://+:8080 Set the API Documentation to Swagger UI. This will allow the server to host Swagger UI documentation for our API. 14. Rename the solution to QuickProductAPI. Do this by clicking on the solution in the solution explorer and then changing the name property then saving the solution. This is important because it will reflect as such on the Linx Server. Renaming it will make the solution easier to identify when you have more than one solution deployed. 15. 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. 16. 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 the 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: In the Linx Designer, click Deploy Set up the server using the credentials you have received Click the Save button Click the ‘DEPLOY & OPEN SERVER’ The solution will be deployed and the server will be opened once the solution is deployed to the server. 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. When you open the Server, and the solution is uploaded and ready to use, it should look like this: 17. Click on the ProductAPI Solution, and then turn the RestHost service on 18. 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 . Add ‘/swagger’ to access the swagger documentation. The address will look similar to this: 19. ‘[my-domain].api.linx.twenty57.net‘ https://xxxxxx11.api.linx.twenty57.net/swagger You are now ready to test the hosted API Consuming: Call the API In this section, you will test the hosted API. This can be done by using any API testing tool such as Postman, hoppscotch.io or even a web browser. To call the API, the Linx Server is set up in such a way that your API is hosted at your server name . Add the endpoint paths behind this hosted address to call the endpoint. ‘[my-domain].api.linx.twenty57.net‘ Test getAllProducts. Do this by calling the below URL modified with your server name ( ) in any browser (or testing tool): 20. replace the xxxxxx11 with your server name https://xxxxxx11.api.linx.twenty57.net/products Test GetProductByID. Do this by calling the below URL modified with your server name ( ) in any browser (or testing tool): 21. replace the xxxxxx11 with your server name https://xxxxxx11.api.linx.twenty57.net/productByID?id=1 Call the GetProductByID endpoint with id = -1 at least once, this will force an internal server error. This will allow you to see how Linx Server displayed errors. 22. https://xxxxxx11.api.linx.twenty57.net/productByID?id=-1 You can now head back over to the Linx server to view the monitoring and logging of events. Open the solution to view the events and errors in the dashboard. To view errors, click on the red indicator on the dashboard. Alternatively, click on Log to view displayed errors. 23. You have now: 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. To do so, start . here Also published . here
