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 low-code developer tool. All stacks that integrate with Conduit will integrate with the newly created API.
Note: Building an API requires development strategies and precise planning. Since we are replicating an existing API, and using Linx for development, these strategies slightly differ from building an API from scratch.
Technologies and tools used to develop RealWorld API:
Try it! The completed Linx implementation of the sample can be found in our GitHub repository.
Planning the RealWorld API
As with every API, you will need to go through the typical stages of development.
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 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.
Low-code API development guides
- Design-first using an OpenAPI specification
- Code-first API builder, fast implementation, including hosting and documentation
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.
- Authenticate users via JWT
- CRU* users (sign up)
- CRUD Articles
- CR*D Comments on articles (no updating required)
- 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.
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
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.