subZero GraphQL/REST API Starter Kit

Base project and tooling for authoring data API backends with subZero.

Runs Anywhere

Run subZero stack as a hassle-free service (free plan available) or deploy it yourself anywhere using binary and docker distributions.

Features

✓ Out of the box GraphQL/REST endpoints created by reflection over a PostgreSQL schema
✓ Authentication using email/password or using 3rd party OAuth 2.0 providers (google/facebook/github preconfigured)
✓ Uses PostgREST+ with features like aggregate functions (group by), window functions, SSL, HTTP2, custom relations
✓ Cross-platform development on macOS, Windows or Linux inside Docker
✓ PostgreSQL database schema boilerplate with authentication and authorization flow
✓ Debugging and live code reloading (sql/configs/lua) functionality using subzero-cli
✓ Full migration management (migration files are automatically created) through subzero-cli
✓ SQL unit test using pgTAP
✓ Integration tests with SuperTest / Mocha
✓ Community support on Slack

✓ Scriptable proxy level caching using nginx proxy_cache or Redis

Directory Layout

.
├── db                        # Database schema source files and tests
│   └── src                   # Schema definition
│       ├── api               # Api entities available as REST and GraphQL endpoints
│       ├── data              # Definition of source tables that hold the data
│       ├── libs              # A collection of modules used throughout the code
│       ├── authorization     # Application level roles and their privileges
│       ├── sample_data       # A few sample rows
│       └── init.sql          # Schema definition entry point
├── html                      # Place your static frontend files here
├── tests                     # Tests for all the components
│   ├── db                    # pgTap tests for the db
│   ├── graphql               # GraphQL interface tests
│   └── rest                  # REST interface tests
├── docker-compose.yml        # Defines Docker services, networks and volumes
└── .env                      # Project configurations

Installation

Prerequisites

• Docker
• Node.js
• subzero-cli

Create a New Project

Click [Use this template] (green) button. Choose the name of your new repository, description and public/private state then click [Create repository from template] button. Check out the step by step guide if you encounter any problems.

After this, clone the newly created repository to your computer. In the root folder of application, run the docker-compose command

docker-compose up -d

The API server will become available at the following endpoints:

• Frontend http://localhost:8080/
• REST http://localhost:8080/rest/
• GraphQL Simple Schema http://localhost:8080/graphql/simple/
• GraphQL Relay Schema http://localhost:8080/graphql/relay/

Try a simple request

curl http://localhost:8080/rest/todos?select=id,todo

Try a GraphQL query in the integrated GraphiQL IDE

{
  todos{
    id
    todo
  }
}

Development workflow and debugging

Execute subzero dashboard in the root of your project.
After this step you can view the logs of all the stack components (SQL queries will also be logged) and if you edit a sql/conf file in your project, the changes will immediately be applied.

Unit and integration tests

The starter kit comes with a testing infrastructure setup. You can write pgTAP tests that run directly in your database, useful for testing the logic that resides in your database (user privileges, Row Level Security, stored procedures). Integration tests are written in JavaScript.

Here is how you run them locally

yarn install         # Install test dependencies
yarn test            # Run all tests (db, rest, graphql)
yarn test_db         # Run pgTAP tests
yarn test_rest       # Run rest integration tests
yarn test_graphql    # Run graphql integration tests

All the test are also executed on on git push (on GitHub)

Deployment

The deployment is done using a GitHub Actions script. The deploy action will push your migrations to the production database using sqitch and the static files with scp. The deploy step is triggered only on git tags in the form of v1.2

Note that the deploy action pushes to production the database migrations (db/migrations/) not the current database schema definition (db/src/) so you'll need execute subzero migrations init --with-roles before the first deploy and when iterating, you'll create new migrations using subzero migration add <migration_name>

You'll also need to configure the following "secrets" for your github deploy action

PRODUCTION_DB_MASTER_USER
PRODUCTION_DB_MASTER_PASSWORD
PRODUCTION_DB_HOST
PRODUCTION_DB_PORT
PRODUCTION_DB_NAME
SFTP_USER
SFTP_PASSWORD
SUBZERO_PASSWORD
SUBZERO_EMAIL
SUBZERO_PASSWORD
SUBZERO_APPLICATION_ID

While the deploy action is written for subzero.cloud (DEPLOY_TARGET: subzerocloud) it can easily be adapted for other deploy targets that run the subzero stack

Contributing

Anyone and everyone is welcome to contribute.

Support and Documentation

• subZero Documentation
• PostgREST API Referance
• PostgreSQL Manual
• Slack — Watch announcements, share ideas and feedback
• GitHub Issues — Check open issues, send feature requests

License

Copyright © 2017-2021 subZero Cloud, LLC.
This source code in this repository is licensed under MIT license
Components implementing the GraphQL interface (customized PostgREST+ and OpenResty docker images) are available under a commercial license
The documentation to the project is licensed under the CC BY-SA 4.0 license.