RealWorld API: How to build it in low-code

Planning the RealWorld API

As with every API, you will need to go through the typical stages of development.

Determining requirements

It is essential to gather and understand requirements for endpoints to have defined use cases. The RealWorld App project has strict requirements that any implementation must follow. The first step is understanding 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 from RealWorld. Although RealWorld API provides API documentation alongside the Postman collection, some parameters and responses were not the same across all documentation.

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.

API configuration and security

API Configuration is vital in implementing data integrity and security, endpoints, responses, queries, and parameters. The API configurations must be identical to Conduit to build an API compatible with the existing front end. 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.

Database design and architecture

Storing and pulling data from 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.

Developing the RealWorld API

We’ve used Linx as the development tool. Building an API with Linx is relatively simple as it is a low-code platform that can be used for development and exposing APIs, including hosting.

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

Use of OpenAPI 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 service instance is created within the Linx Designer. The endpoints can be tested from a browser or any preferred testing tool. Thus, the web service’s configuration and logic 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.

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 allows us 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, some deviated slightly from the specification, so 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

https://github.com/angelguzmaning/ts-redux-react-realworld-example-app

https://github.com/wesib/realworld-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.

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.