Easily Build GraphQL APIs with Prisma

The technology sector is reeling after an official statement was released by the UN's International Council of Coolness last week. The statement clearly states what status-quo developers have feared for months: if you haven't shifted from REST to GraphQL by now, you are officially recognized by the international community to hold "uncool" status. A humanitarian crisis is already unfolding as refugees of coolness are threatening to overtake borders, sparking fears of an influx of Thinkpad Laptops, IntelliJ, and other Class A uncool narcotics.

Hold up: is GraphQL That Dramatic of an Improvement over REST?

In all honesty, I've found that the only way to properly answer this question is to first utter "kinda," then mull back and forth for a little while, and then finishing with a weak statement like "so pretty much, yeah."

Let’s put it this way. When you’re first familiarizing yourself with a set of data, what do you do? Do you read extensive documentation about the SQL table you’re about to check out? Do you read the entire spec for your version PostgreSQL to see if it contains the functionality that might be missing for some reason? I’m going to guess you do neither of these- chances are you just look at the data.

Using any REST API is inherently a context-switch. No matter how many APIs you’ve worked with in the past, you’ll never be able to know a new API’s endpoints, quirks, or the awful manner in which the creator has abandoned any distinction between GET, POST, or PUT methods altogether. GraphQL is not necessarily more technologically impressive than REST, but it does provide us a syntax and workflow comparable to working directly with databases with which we're already familiar.

Remember when us young guys justified replacing older devs when we came out of the gate with NodeJS, arguing that context-switching changes everything? GraphQL is just that: a "better" technology with less mental context-switching, which conveniently serves a double-purpose for enterprises looking to fire anybody they perceive to be dead weight over the age of 30. Good luck finding a better synopsis than that.

What’s this Prisma Nonsense?

Prisma is a free (FREE!) service that provides with the tools to create an API client, as well as an Admin panel to manage it. Without any prior knowledge of GraphQL needed, Prisma provides us with:

• A CLI which’s stand up a web server which will serve as our API: either cloud or self-hosted.
• Automatic integration with your database of choice (including cloud DBs, such as RDS).
• A clever obfuscation of data models via a simple config file. No classes, no code, no bullshit.
• A "playground" interface which allows us to mess around in GraphQL syntax against our models without breaking everything.
• A web GUI which displays the relationships between all of these things and their usage.

In short, Prisma does our jobs for us. Now that tasks associated with building APIs, creating ORMs, and managing databases have all been trivialized, we can finally cut some more of that dead weight we mentioned earlier- specifically Bob, the asshole coming up on his 35th birthday sitting on his high-horse just because he has an obligation to feed 3 beautiful children. Sorry Bob, it just wasn't working out.

Prisma does provide the option to set up a test environment on their cloud, but let's do something useful with our lives for once and build something production-ready. In this case, that means standing up a 5-dollar Digital Ocean Droplet.

Create a Prisma Account

Get over to the sexually appealing Prisma Cloud landing page and make yourself an account. When prompted, make sure you select Deploy a new Prisma Service.

You should then be prompted with the following screen. It will instruct you to install an NPM package, but there are a few things we need to do first.

Installing Prisma Dependencies on a Fresh VPS

SSH into whichever VPS you've chosen. I'll be using a Ubuntu instance for this tutorial. If you happen to be using Ubuntu as well, feel free to copy + paste all the stuff I'm sure you've done a million times already. First, we need to install Node:

$ apt update
$ apt upgrade
$ curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash -
$ sudo apt-get install -y nodejs

Before you do anything crazy like copy & paste those two lines from Prisma, you're going to need to set up Docker a few steps later, so you might as well do that now:

1. Install Docker Dependencies

$ sudo apt-get install \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg-agent \
    software-properties-common

2. Add Docker Key

$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
$ sudo apt-key fingerprint 0EBFCD88

3. Get Docker Repository

$ sudo add-apt-repository \
   "deb [arch=amd64] https://download.docker.com/linux/ubuntu \
   $(lsb_release -cs) \
   stable"

4. Finally Install Docker

$ sudo apt-get update
$ sudo apt-get install docker-ce docker-ce-cli containerd.io

Good job, you're doing great.

Install & Activate The Prisma CLI

Cool, now we can carry on with Prisma's demands:

$ npm install -g prisma
$ prisma login -k eyJhbGciGYU78tfuyLALALTHISKEYISFAKELOL69KFGs

After we've successfully logged in, the next step will create the local files which serve as the heart and soul of our API. Make sure you init Prisma in whichever directory you like to keep things in:

$ cd /my/desired/directory/
$ prisma init my-prisma

Initiating the project will kickstart a quick and painless interrogation process. Keep in mind that it's recommended to use Prisma with a fresh database instance; in my case, I spun up a cloud PostgreSQL instance.

? Set up a new Prisma server or deploy to an existing server? Use existing database
? What kind of database do you want to deploy to?:
? Does your database contain existing data?:
? Enter database host:
? Enter database port:
? Enter database user:
? Enter database password: 
? Enter database name (the database includes the schema):
? Use SSL?:

Completing this will result in the following structure:

my-prisma
├── datamodel.prisma
├── docker-compose.yml
├── generated
│ └── prisma-client
│ ├── index.ts
│ └── prisma-schema.ts
└── prisma.yml

We're almost there cowboy and/or cowgirl.

Set Phasers to "Deploy"

Prisma is going to stand itself up on port 4466 , which is closed by default on most servers. Make sure you have this port open:

$ ufw allow 4466

Finally, we need to set a secret in order to connect to Prisma cloud. Open the docker-compose.yml file and uncomment the managementApiSecret line. Replace the value with some sort of deep dark personal secret of yours.

$ vim docker-compose.yml


version: '3'
services:
  prisma:
    image: prismagraphql/prisma:1.25
    restart: always
    ports:
    - "4466:4466"
    environment:
      PRISMA_CONFIG: |
        port: 4466
        # uncomment the next line and provide the env var PRISMA_MANAGEMENT_API_SECRET=my-secret to activate cluster security
        managementApiSecret: my-secret
        databases:
          default:
            connector: postgres
            host: 123.45.678.90
            database: databasename
            user: username
            password: password
            rawAccess: true
            port: '5432'
            migrations: true

Reiterating the comment in our yml file, export the same secret you stored as an environment variable in your Prisma directory.

$ export PRISMA_MANAGEMENT_API_SECRET=my-secret

It's Game Time

It's time to deploy, baby!!! Do it, push the button! DO IT NOW!

$ docker-compose up -d
$ prisma deploy

Deploying for the first time does to things: it'll stand up a playground interface on your server (localhost:4466) as well as get you going with the Prisma Cloud Interface.

Check Out Your Workspace

Visit your server's IP:4466 to see what you've done:

Check it outtttt man! Along with documentation of the generic data models Prisma shipped with, you can test queries or mutations on the left side of the UI, and receive responses on the right. Sure beats Postman imho.

Don't Look Down: You're in the Cloud

You can now add your server to Prisma Cloud to get the benefits of their admin panel. From here, you can modify information directly, review usage metrics, and manage multiple instances:

Working With Prisma

Now that we've spun up this shiny new toy, let's be sure we know how to drive it.

On your VPS, take a look at the datamodels.prisma file:

$ vim datamodels.prisma

You should see a data model called User (everybody has this model). To add or modify data models, all we need to do is change the fields as we see fit, set their data type, and specify whether or not we'd like the field to be unique. Below I've added a couple of new 'fields.'

type User {
  id: ID! @unique
  name: String!
  email: String! @unique
  gravatar: String!
}

Deploying Prisma again with these changes will modify our database's table structure to match the new model:

$ prisma deploy

There you have it: one more buzzword to put your resume. In fact, feel free to completely falsify the existence of a GraphQL certification and throw that on there, too. If you're the kind of person who enjoys reading technical posts like this in your free time, chances are you're already qualified for the job. Unless you're Bob.