RealWorld is a popular open-source project known as the mother of all demo apps. It is an exact clone of Medium.com (called Conduit) and can be built using any front-end and back-end.
This article will share the journey to replicating the RealWorld REST API (Conduit) from scratch using Linx, a general-purpose low-code developer tool. All stacks that integrate with Conduit will integrate with the newly created API.
Technologies and tools used to develop RealWorld API:
Development tool - Linx
Deployment tool - Linx
API testing and editing tool (Postman) - Postman
Database (MySQL)- Mysql
Notes
Building an API requires development strategies and clear planning. Since we are replicating an existing API, and using Linx for development, these strategies slightly differ from building an API from scratch.
The completed Linx implementation of the sample can be found in our GitHub repository.
A. Planning the RealWorld API
As with every API, you will need to go through the typical stages of development.
1. Determining requirements
It is essential to gather and understand requirements to have defined use cases for endpoints. The RealWorld App project has strict requirements that any implementation must follow. The first step is to understand the API definition provided in the RealWorld project, including each endpoint’s requests and responses.
We’ve used the Postman collection provided in the RealWorld API project to exchange data with Conduit to understand the existing functionalities clearly. However, while analyzing the functionalities, we noticed incompatibility among the documents provided from RealWorld. Although RealWorld API provides API documentation alongside the Postman collection, some parameters and responses were not the same across all documentation.
2. API Architecture
API documentation comprises mainly planning, designing, and reviewing the construction of APIs and enforcing developer guidelines. We’ve followed the same architecture provided in the RealWorld swagger 2.0 JSON API file.
Linx immediately creates all the associated operations under the RESTHost plugin when the swagger definition is imported.
Associated operations are created under RESTHost when the swagger definition is imported.
3. API Configuration and Security
API Configuration plays a vital role in implementing data integrity and security, endpoints, responses, queries, and parameters.
To build an API compatible with the existing front-end, the API configurations must be identical to Conduit. The following basic configurations of REST APIs must be the same as the RealWorld API:
- Security and Authentication
- Methods (Endpoints, query values, body, etc.) and parameters (supported data formats)
- Handling response data (HTTP Status Codes, responses). Open API supports multiple authentications and authorization schemes specified with the “security scheme” component. For example, the RealWorld API uses API keys with JWT token for authorization.
Linx provides built-in functions to generate and verify JWT Tokens, facilitating the authentication scheme’s implementation.
4. Database Design and Architecture
Storing and pulling data out of a database to exchange with an API can be challenging. So we’ve decided to host our data source for data persistence.
Linx has plugins that allow connection with various databases. Since it is freely available, MySQL was the best option as a database source. It is preferred to have the database hosted on a remote server in the cloud to limit the extent of a cyber attack by adding an extra layer of security. Once we had finalized the database architecture, we were ready to move to the next step.
B. Developing RealWorld API
We’ve used Linx as the development tool. Building an API with Linx is rather simple as it is a low-code platform that can be used for development and exposing APIs, including hosting.
1. Building the API
Once all the necessary information had been gathered and identified, we started building the core requirements, which could be rapidly scaled in the first iteration. Then, we identified and built the secondary requirements in the second iteration.
Core requirements:
- Authenticate users via JWT
- CRU* users (sign up)
- CRUD Articles
- CR*D Comments on articles (no updating required)
Secondary requirements:
- GET and display paginated lists of articles
- Favourite articles
- Follow other users
2. Use of Open API Specifications (OAS)
Debugging API in real-time before deployment
Linx debugger facilitates debugging of the RESTHost API in real-time before deployment. When debugging a RESTHost in Linx, a local instance of the service is created within the Linx Designer. The endpoints can be tested from a browser or any preferred testing tool. Thus, both the configuration and the logic of the web service can be debugged and tested with real-time data.
Test Using the interactive API documentation
The purpose of API testing is to check the functionality of your API. Linx renders OpenAPI specs as interactive API documentation. The latter involves automatically generating the API documentation of the service. Linx provides the option of generating the documentation both in swagger and Redocly.
Once the actual API definition of the web service is generated, you can further use it externally for testing and it can be imported into any other solution. The interactive documentation shares common examples and structures over those written or generated as part of a build/deployment process.
API documentation automatically generated using swagger: https://demo.api.linx.twenty57.net/realworld/swagger
Test using Postman
There are many third-party API testing tools. We’ve used the Postman collection in the RealWorld project to test the newly created endpoints. This gives us an additional opportunity to improve the API design further and fix any identified issues before the production release.
Integration test with existing front-ends
Since many free front-end apps are available that integrate with the RealWorld API, we’ve used a range of them to test our endpoints to ensure compatibility. Unfortunately, we found that some deviated slightly from the specification, and therefore, we can’t account for all apps. However, we tried to find the middle ground to get a maximum number of functions to work.
Front-end Results
Conduit Frontend
https://github.com/angelguzmaning/ts-redux-react-realworld-example-app
Deployment/Exposing the API
Deployment options (on-premises, cloud) vary with requirements. With Linx, you can host your solution on-premise or in the cloud, directly from the IDE.
The public API is exposed (demo server): https://demo.api.linx.twenty57.net/realworld/swagger/index.html?url=/realworld/documentation/openapi.json
C. Maintenance
Traffic monitoring from Linx Server Dashboard
Finally, after exposing the APIs, services and events can be monitored using the all-in-one Linx server dashboard. It provides real-time management of services, including logging, metrics, and version history. It can also be helpful when debugging services.
If you want to try and connect to the new RealWorld API with front-end apps or use it as a back-end, it is freely available on https://demo.api.linx.twenty57.net/realworld/swagger
The completed Linx implementation of the sample can be found in our GitHub repository.
The post Building the RealWorld API in Low-code appeared first on Linx.
Top comments (0)