Chinchay Docs

# Overview: What is Chinchay?

Ufff this is a tough question.... going technical, Chinchay is a npm package that works on top of express.js (and therefore node.js) and connects to a postgreSQL database through knex.js, a SQL query builder.

When building a large application order is a key factor, very easily the repository becomes a big plate of spaghetti! Basically just chaos.

# What Chinchay Aims To Solve

Chinchay aims to speed up your development without compromising code quality. In my early programming years I had these problems:

  • Organizing the files
  • Following industry best practices
  • Managing the updates to the database
  • Making a good api
  • Managing user access: who can access what
  • Managing HTTP status codes are responses correctly
  • Avoid copy-pasting programming, specially for CRUD operations. I was doing over and over the same operations with minimal changes.

It was then that I decided to build a package that would allow me to tackle each of these issues. This package includes both a Command Line Interface and many tools to solve each problem.

# So what does Chinchay actually do?

  • Use Chinchay’s CLI to automate CRUD (Create, Read, Update, Delete) operations. It will follow a MVC(Model View Controller) architecture pattern. With it, I can assure you coding will not be tedious nor time consuming. Chinchay tries not to be highly-opinionated and favours flexibility, therefore is fully customizable through the .chainfile.js.
  • Chinchay’s CLI will create an API following the REST application architecture.
  • If you do not use the Chinchay CLI, Chinchay does offer a HATEOAS generator that can be added to your API, one step forward towards a RESTful API.
  • Chinchay provides an ErrorHandler to manage HTTP status codes, returning meaningful messages and codes.
  • Protect your app, so that only authorized users access the data. Use Chinchay Access Module, Chinchay’s middleware and Chinchay’s sister package TheWall to fully control who can access what. See the API tutorial for a complete guide!
  • Chinchay’s CLI will also create Frontend views to work with the generated API. It can either be with ejs or Angular. [Currently working in more frontend options!]
  • Chinchay allows API clients to customize their queries. With just a couple of endpoints and a very simple syntax, API clients can query what they need. Obviously this can be limited and disabled as needed. See API: Client Querying for more!
  • Last, But definitely not least, Chinchay offers a flexible and extendable Table Gateway Model. To organize and manage your database queries without even knowing any SQL.

# File Structure: Model-View-Controller (MVC) Architecture

For starters, let's begin with a disclaimer: I did not reinvent the wheel. Chinchay uses the state-of-the-art, in this case it was MVC Architecture. If you do not know what that is, here are a list of useful links:

But in a nutshell, the code is logically separated in three areas. The model, where the logical-business code is written. They are the gateway to the database and would do most of the "important" work. The view manages all the UI logic and the controller is the interface that connects the view with the model.

The Command Line Interface will allow you to generate files in this pattern to keep everything organized and clean.

# Updating the Database

Chinchay works with PostgresQL. This is the database system that stores the data. As you may know the data is saved in tables. So how do we actually create or modify these tables?

# Schema Migrations

A schema migration is a piece of code that does one change to the database. Not only has the code to effectuate that change, but also has the code to revert that change. For instance if we add the column user_id to the table coffees but then regret that decision, we can rollback that migration, removing the column user_id. Here are some articles you might find interesting:

I guess you are asking yourself how this actually works, the answer is: knex.

# knex

knex is the magical tool that will manage all the migrations. Every time you need to make a change to the database you make a knex migration as follows:

$ knex migrate:make migration_name

That will create a code that usually goes something like this:

  exports.up = function (knex) {
    // code to make the change in the database
  };

  exports.down = function (knex) {
    // code to revert the change in the database
  };

In the up function you write the code for the change and in the down function the code to revert the change of the up function.

Then just run the following to apply the change (it will execute the up function):

$ knex migrate:make latest

If you want to revert it, run the following (it will execute the down function):

$ knex migrate:make rollback

When you use the Chinchay Command Line Interface to create migrations it will use this. For more information on migrating with knex go to the documentation.

# Why postgresQL and not another database system?

To be honest, just because. PostgreSQL is one of the most popular databases and it seemed like a good starting point. At the moment we are working to make Chinchay compatible with mysql and other databases, actually if you are a database expert help us out making Chinchay compatible with more databases!

# REST API

The next big thing was: how to do a good api?

And the answer is a flexible RESTful API. If you do not know what a RESTful API is, I recommend reading this article. In a nutshell a RESTful API is an architectural style presented by Roy Fielding that suggests a way to model the client-server interaction.

Not every API that says it's REST actually is REST. Most of the APIs out there who declare themselves as REST APIs actually are not. REST enforces some strict protocols which are hardly ever fulfilled. Aaaand enter Chinchay, Chinchay will separate the code in a layered system which is stateless and cacheable. Moreover, to make a uniform interface it has a fully flexible HATEOAS generator.

# HATEOAS

HATEOAS is one of the most distinctive features of a REST API and is hardly ever present. HATEOAS tries to mimic our real-life browsing, when we visit a page all the possible links are presented (as buttons, images, etc). HATEOAS aims to do the same, in which every API request a list of followup links are given. However, doing so it's a pain in the *** for the developer, he is responsible to, for every API request, return all the followup links. So guess what does chinchay do? Yes it will make it veeery easy to do so with it's HATEOAS generator.

You can read more about HATEOAS here.

# Client Queries

Well so we now have a RESTful API with HATEOAS, is that a good api? Well, not necessarily... A GOOD API is an API that is both elegant and useful.

  • Elegant: ✅ (it's REST, so yeah it is elegant)
  • but how do we make it useful?

For it to be useful, the client must be able to extract the information it needs through it. Chinchay provides a complete flexible interface where the client can build specific queries to consult information. The backend developer does not need to do a different API endpoint for each client need, with a few endpoints and a flexible querying interface everything is possible. Read more on how to do so here.

# oAuth 2.0

If by this point you are thinking, wait, the client can ask whatever he wants, so is it unsafe or how do we control him to only access what he should access? Do not worry! Chinchay has you covered!

You can easily transform your API into an oAuth 2.0 API, oAuth is an industry-standard protocol for authorization. In simple terms, you can protect so each user only access the endpoint you give him access to.

So the whole process go like this:

  1. The user authenticates with it's credentials (usually a username and password)
  2. If the credentials are correct an access token is generated and given to the user. This token has an expiration date.
  3. Every request the user does to the API it must provide the access token, otherwise the connecting is denied.

# So how does Chinchay make the API an oAuth 2.0 API?

The Chinchay Middleware will be in charge of inspecting that the token is present, valid and that the user of that token has access to the given endpoint. The token is expected to be given as a Bearer Token.

The Access Module will be in charge of generating the access token, the token follows the json web token standard, by generating the token with the jsonwebtoken npm package.

To actually define which user has access to which endpoints, chinchay uses the TheWall npm package. In the Middleware documentation you will be guided on how to work with each of these tools.

Moreover you might have one route that it's accessible by different users but the content must be different. For instance, with chinchay (running locally) the route: http://localhost/api/coffee/find will return all the coffees. If we have a customer1 user and a customer2 user, we might want to use that endpoint to return all the coffees that the user has access to. So how do we filter them? With TheWall we give access to both users to that route, but with the Access Module we can add the corresponding filter so that when the information is fetched to the database only the corresponding coffees are given.

REMINDER

Do remember that the using oAuth is optional, you might have an API that is accessible for everyone and if that's fine with you Chinchay will be fine as well.

If you have more doubts of how oAuth works, check this links:

Command Line Interface →