aureliechicart / oblog

Training project - Simple blog API to compare REST API and graphQL API

Blog API ✏️

Introduction

Simplistic API for a blog with posts and categories. REST API on branch master (CRUD routes for post entity). Same API served as GraphQL on GraphQL branch.

Learning goals

Database

• Database modeling: project MCD/MLD
• Database versioning: setting up a sqitch project and adding migrations to create tables
• Seeding: importing data from json files using a script
• Using CREATE VIEW sql command

Architecture

• creating Express app
• creating Active Record models
• creating controllers

Swagger API Documentation

• Documenting router and models using JSDoc syntax
• Generating API Swagger documentation based on JSDoc code

Data validation with Joi

Data validation using Joi

• Setting up a Joi schema to describe the expected criteria for the creation of a new blog post
• Creating a validator middleware checking the request body against the sdefined Joi schema
• Adding this middleware in router so it is executed before the POST controller method

Implementing a Redis cache

• Setting up a Redis store to be used for caching
• Creating a cache middleware and a flush middleware with time-based invalidation (data in cache will expire after the defined time) and event-based invalidation (if a new blog post is created, then the posts data is flushed from the cache)
• Placing those middleware in router

Setting up the same API but with GraphQL (see 'graphQL' branch)

• Setting up GraphQL server
• Adding schema (types and resolvers)
• Testing queries and mutations in GraphQL playground

Technologies

• Node v16.14.0
• Express v4.17.2
• postgreSQL 12 database server
• pg (PostgreSQL client) v8.7.1
• sqitch v0.9999
• Redis v.6.2.6
• redis (client) v4.0.1
• dotenv v14.3.2
• cors v2.8.5
• express-swagger-generator v1.1.17
• joi v17.6.0
• graphql-yoga v1.18.3

Install

Clone this repository.

In the terminal, at the root of the folder project, run the following command to install the dependencies:

npm i

Database creation and seeding

Install potsgreSQL, start it using command sudo service postgresql start and create a local PostgreSQL database:

createdb <database_name>

Install sqitch and deploy the sqitch plan on your new database:

sqitch deploy db:pg://<pg_user>:<pg_password>@localhost:<pg_port>/<database_name>

Then run this js script to populate the database:

psql -d <database_name> -f /data/import.js

Redis

This project uses a Redis store for caching. Install redis and make sure the server is running using the redis-server line command.

Setting Environment Variables

Copy the .env.example file and update it with PORT and your postgres database connection parameters.

Launch Command

Run the following command to start the server:

npm run dev

To test your access, go to localhost:<port>/v1/posts.
⚠️ Note the use of the prefix 'v1' in the path of the API endpoints' URI.

Swagger

To access the Swagger doc and discover the available API endpoints, go to http://localhost:<port>/api-docs.

Testing the GraphQL API

Checkout the graphQL branch:

git checkout graphql

Run the npm i command to install graphql-yoga.
Restart the server and visit http://localhost:<port> in your browser to access the graphQL playground. There, you can build and run queries and mutations against graphQL server.
Review this file for query and mutation examples adapted to this API.