Building Books API using Platformatic

In this tutorial we will explore how to build a books API using Platformatic and PostgreSQL as the database backend.

Initialize the developer environment

First, let's initialize the developer environment from the terminal.

$ mkdir books-api
$ cd books-api/
$ npm init -y
$ npm i platformatic@latest fastify@latest
$ npx create-platformatic@latest
Need to install the following packages:
create-platformatic@1.31.1
Ok to proceed? (y)
 Hello Jericho Rivera, welcome to Platformatic 1.31.1!
? What kind of project do you want to create? Application
? Where would you like to create your project? .
? Which kind of project do you want to create? DB
? What is the name of the service? books-db
? What is the connection string? sqlite://./db.sqlite
? Do you want to create default migrations? no
? Do you want to create another service? no
? Do you want to use TypeScript? no
? What port do you want to use? 3042
[09:53:21] INFO: /Users/jerichorivera/Workspace/nodejs/books-api/package.json written!
[09:53:21] INFO: /Users/jerichorivera/Workspace/nodejs/books-api/platformatic.json written!
[09:53:21] INFO: /Users/jerichorivera/Workspace/nodejs/books-api/.env written!
[09:53:21] INFO: /Users/jerichorivera/Workspace/nodejs/books-api/.env.sample written!
[09:53:21] INFO: /Users/jerichorivera/Workspace/nodejs/books-api/.gitignore written!
[09:53:21] INFO: /Users/jerichorivera/Workspace/nodejs/books-api/README.md written!
[09:53:21] INFO: /Users/jerichorivera/Workspace/nodejs/books-api/services/books-db/package.json written!
[09:53:21] INFO: /Users/jerichorivera/Workspace/nodejs/books-api/services/books-db/platformatic.json written!
[09:53:21] INFO: /Users/jerichorivera/Workspace/nodejs/books-api/services/books-db/plugins/example.js written!
[09:53:21] INFO: /Users/jerichorivera/Workspace/nodejs/books-api/services/books-db/routes/root.js written!
[09:53:21] INFO: /Users/jerichorivera/Workspace/nodejs/books-api/services/books-db/test/helper.js written!
[09:53:21] INFO: /Users/jerichorivera/Workspace/nodejs/books-api/services/books-db/test/plugins/example.test.js written!
[09:53:21] INFO: /Users/jerichorivera/Workspace/nodejs/books-api/services/books-db/test/routes/root.test.js written!
[09:53:21] INFO: /Users/jerichorivera/Workspace/nodejs/books-api/services/books-db/.gitignore written!
[09:53:21] INFO: /Users/jerichorivera/Workspace/nodejs/books-api/services/books-db/README.md written!
[09:53:21] INFO: /Users/jerichorivera/Workspace/nodejs/books-api/services/books-db/global.d.ts written!
? Do you want to init the git repository? no
⠦ Installing dependencies...
[09:54:06] INFO: Project created successfully, executing post-install actions...
[09:54:06] INFO: You are all set! Run `npm start` to start your project.

Configure the application

Open the folder in VS Code and edit the following lines inside tne .env file:

PLT_SERVER_HOSTNAME=127.0.0.1
PLT_BOOKS_DB_DATABASE_URL=postgres://user:password@127.0.0.1:5432/postgres
PLT_BOOKS_DB_APPLY_MIGRATIONS=false

Platformatic supports many database backends so you may edit the DB URL based on your needs.

Next, let's create the migrations folder:

$ mkdir services/books-db/migrations

Migrations

Now we're ready to create our first migration.

$ npx platformatic db migrations create --config services/books-db/platformatic.json

This should create an 001.do.sql and 001.undo.sql files inside the migrations folder.

Edit the file based on your specifications. Standard SQL DDL commands are accepted.

Once you're ready you can execute the DDL with the apply directive.

$ npx platformatic db migrations apply --config services/books-db/platformatic.json

Start the application

Let's start the application and open and access the client:

$ npm start

> start
> platformatic start

[10:19:14.775] INFO (books-db/95352): Server listening at http://127.0.0.1:3042

If everything worked up to this point you should have an OpenAPI endpoint and a GraphQL endpoint.

Seed the Database

This procedure is as easy as creating a seed file and and executing it with:

$ npx platformatic db seed path/to/seed.js --config services/books-db/platformatic.json

You can find my sample seed file here.

Protecting the API routes

It is important that we protect our API routes to avoid abuse. Let's add an admin secret key and rules for entities.

Edit the file in services/books-db/platformatic.json to add the authorization object.

"authorization": {
    "adminSecret": "{PLT_AUTH_ADMIN_SECRET_KEY}",
    "rules": [
      {
        "entities": ["book", "author", "publisher"],
        "role": "platformatic-admin",
        "find": true,
        "save": true,
        "delete": false
      },
      {
        "entities": ["book", "author", "publisher"],
        "role": "anonymous",
        "find": true,
        "save": false,
        "delete": false
      }
    ]
  },

This will prevent save and delete actions from anonymous users and prevent delete from admin users while allowing find action to any user.

If you are still interested you can check my books-api github repo.