As a Distributed Systems 2020–21 Class project, COVIDSymptomReportAPI is a idea that as the objective to give to any citizen the opportunity to create a Report when suspected to have symptoms related to SARS-CoV-2. This idea, was developed considering a scenario where a medical team would use this API as a resource for response / supervision / analysis and acknowledgement regarding the COVID Symptoms situations related.
Let’s keep in mind that this is a academic project, where we was learning along the way and adapt the project as we were acknowledge something new, because we believe that there are many other ways to develop this project for better.
As some requirements by the teacher class, this API will it have in consideration the following points:
- MongoDB: a source-available cross-platform document-oriented database program;
- Swagger: Interface Description Language for describing RESTful APIs expressed using JSON.
- Microsoft Azure: commonly referred to as Azure, is a cloud computing service created by Microsoft for building, testing, deploying, and managing applications and services through Microsoft-managed data centers.
And as optional, the implementation of:
- Authentication: the act of proving an assertion, such as the identity of a computer system user.
- GraphQL: a open-source data query and manipulation language for APIs, and a runtime for fulfilling queries with existing data.
Note: As a academic project, the development of COVIDSymptomReportAPI did have in consideration of some student subscriptions (ex: Microsoft Azure).
[ API Architecture]
In a some way to say it, after we have the initial code for the API to work, we have:
- routing .js files: it routes an incoming HTTP request to a particular action method on the API controller;
- controller .js files: it handles incoming HTTP requests and send response back:
- connector.js: it handles the MongoDB database process's as respective functions on it;
Having the same time consideration with the Swagger’s implementation. The Authentication and GraphQL segments only have been implemented after.
[ Curiosities ]
As the project was developing, we came across with some interesting ideas where we try to learn more than we expected, so don’t be surprise if encounter some content out of context from the original objective. For example, as we know a API output is intended for machines to understand but for simple API’s we could process the output for human read friendly. So, in some of the end-points that we developed we did coded in a way that the output given would be processed to do that. You can see more about that as you continue to read this article.
[ Connecting API to MongoDB ]
In relation of the API, having a account on the MongoDB where we will use a cluster and the respective link to connect our application to it. In the link provided by the cluster we have to considering three things like username, password and the database name where we will put these values in the
nodemon.jsonfile to turning them into environment variables.
[ Initializing the API ]
Having the Visual Studio Code installed on a machine, we create a tree of directories and files as showed below:
├── controllers [directory]
│ ├── authentication_controller.js [file]
│ ├── development_controller.js [file]
│ ├── reports_controller.js [file]
├── custommodules [directory]
│ ├── classes.js [file]
├── graphql [directory]
│ ├── resolvers [directory]
│ │ ├── index.js [file]
│ ├── schema [directory]
│ ├── index.js [file]
├── models [directory]
│ ├── report.js [file]
├── routes [directory]
│ ├── development_route.js [file]
│ ├── general.js [file]
│ ├── reports_route.js [file]
├── connector.js [file]
├── index.js [file]
├── nodemon.json [file]
This was the tree that we ended to as we were adapting the project as we were learning, but in can be improved later for organizational reasons.
With the VSCode terminal, we execute the
npm initcommand in the COVIDSymptomReportAPI path to initialize the and answer the respective questions as desired when they pop up.
Then we import the necessary modules used in the API in the same way:
npm install -save express mongoose email@example.com swagger-ui-express node-json2html express-graphql graphql mongodb npm install nodemon -D
- express: Fast, unopinionated, minimalist web framework for node.
- mongoose: Mongoose is a MongoDB object modeling tool designed to work in an asynchronous environment. Mongoose supports both promises and callbacks.
- firstname.lastname@example.org: reads your JSDoc-annotated source code and generates an OpenAPI (Swagger) specification.
- swagger-ui-express: allows you to serve auto-generated swagger-ui generated API docs from express, based on a
swagger.jsonfile. The result is living documentation for your API hosted from your API server via a route.
- express-graphql: a GraphQL HTTP server with any HTTP web framework that supports connect styled middleware, including Connect itself, Express and Restify.
- mongodb: The official MongoDB driver for Node.js.
- nodemon -D: a tool that helps develop node.js based applications by automatically restarting the node application when file changes in the directory are detected (as a development dependency).
Note: We will use the nodemon to run the API as it uses developer dependencies to work correctly with the environment variables.
For a article friendly read purposes, we will post all code of each file related to this project in the end of this article.
[ Deploying ]
[ Microsoft Azure]
After having the project completed, we did use the Visual Studio Code with the Azure extension to deploy our API.
So with after we sign in on the Azure in the Visual Studio Code and select it on the left panel, we click on the blue arrow to deploy the web app.
Select the folder of the project when asked.
Next, we can create a new Web App or using a pre-existing one, for this time, we created a new one.
To the initial domain of the app, we choose COVIDSymptomReportAPI.
Next, we selected the Node 13 LTS runtime stack.
As it is a academic project, we have selected the Free pricing tier for convenience.
Wait until the process finish and then check the given link on the Azure Portal.
[ Heroku ]
As done in Azure, we decided to learn the deploying of the API in the Heroku, that it works similarly.
Note: In both of the accounts, Azure Portal and Heroku, we added the environment variables related MongoDB link connection to make it work properly.
[ Running It ]
As the both servers are running, we will show examples of the running API using the Heroku link provided.
[ COVIDSymptomReportAPI ]
As we use one of the we will be presented with a homepage as showed. First we will be looking up in the Swagger section and then the GraphQL.
[ Swagger ]
[ End-Points ]
1. [ Authentication ]
This one it permits to Register a New User, Login and Logout. The authentication protects the other end-points sections as Public, Reports, Overview and Development Sections:
2. [ Public ]
This end-point as the purposes to create a new register and stores it into the database:
3. [ Reports ]
As the purpose to analyse data related of Reports stored in the database:
3.1 [ GetAllReports End-Point ]
This end-point it gets all reports stored in the database:
As a very simple function and for learning purposes we work on this in a way to give a human read friendly as is gives a output in html. If we use the API given address we will get something as the picture below:
3.2 [ ReportsCount End-Point ]
This one it gives the total number of existing Reports:
3.3 [ GenderCount End-Point ]
This end-point returns the total number of a specific gender type:
3.4 [ VacineGenderCount End-Point ]
With this one we can get a analysis related to type of gender and the vaccination:
3.5 [ AgeRangeCount End-Point ]
It gets the number of Reports related to various ranges of age:
3.6 [ CustomAgeRangeCount End-Point ]
In this one we can specify a custom age range to retrieve the total number of Reports:
3.7 [ VaccineCount End-Point ]
Retrieves the total number of Reports with the vaccination related:
3.8 [ ChronologicalCount End-Point ]
Returns the number of Reports related to Year, Month and Day:
3.9 [ CustomChronologicalReport End-Point ]
It shows the Reports and number with a specific range of Date (Year, Month, Day) and Time (Hour, Minutes):
3.10 [ ReinfectionCount End-Point ]
Returns the number of people that answered that have been infected before and suspect to be having symptoms by Year, Month and Day:
3.11 [ SymptomRation End-Point ]
This end-point gives a analysis related to a specific chosen symptom, and the percentage of the Reports:
4. [ Overview ]
In this section it has the Overview end-point that it shows a summary of all early end-points. As similar as the GetAllReports end-point, it returns a html code for human read friendly. For development time consumption reasons, we only work on the adaptation of four of the above functions.
5. [ Development ]
In the development section we had created a end-point that generates a specific amount of fictional data and it stores into the database for testing purposes. We input the number of Reports to be created as parameter.
[ GraphQL ]
As a optional requirement, we did implement the GraphQL into our API. Returning to the homepage, we choose the GraphQL interface that will present us the following page:
In the GraphQL we have done two implementations.
The first one it shows the data stored in the database. To exemplify, we will look for name, age, county and q3 (related to the vaccine):
The second implementation it’s a mutation that it create a new Report and stores it into the database:
After the run, we can check it using the GraphQL interface:
And we can use the Swagger to look it up too, using the GetAllReports that has the human read friendly output:
As we talked above, now we will post all the code developed and used in the COVIDSymptomReportAPI.
We hope that you like this article and comment as you like, best regards,