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
✓ Cross-platform development on macOS, Windows or Linux inside Docker
✓ PostgreSQL database schema boilerplate with authentication and authorization flow
✓ OpenResty configuration files for the reverse proxy
✓ RabbitMQ integration through pg-amqp-bridge
(https://www.rabbitmq.com/web-stomp.html)
✓ Lua functions to hook into each stage of the HTTP request and add custom logic (integrate 3rd party systems)
✓ Debugging and live code reloading (sql/configs/lua) functionality using subzero-cli
✓ Full migration management (migration files are automatically created) through subzero-cli/sqitch/apgdiff
✓ SQL unit test using pgTAP
✓ Integration tests with SuperTest / Mocha
✓ Docker files for building production images
✓ Community support on Slack
✓ Enhanced PostgREST+ binary that creates prepared statements instead of inline queries
✓ Live events (with authentication/authorization) through RabbitMQ WebSTOMP plugin
✓ Scriptable proxy level caching using nginx proxy_cache (other backends like Redits possible)

Directory Layout

.
├── db                        # Database schema source files and tests
│   └── src                   # Schema definition
│       ├── api               # Api entities avaiable as REST endpoints
│       ├── data              # Definition of source tables that hold the data
│       ├── libs              # A collection modules of used throughout the code
│       ├── authorization     # Application level roles and their privileges
│       ├── sample_data       # A few sample rows
│       └── init.sql          # Schema definition entry point
├── openresty                 # Reverse proxy configurations and Lua code
│   ├── lua                   # Application Lua code
│   ├── nginx                 # Nginx configuration files
│   ├── html                  # Static frontend files
│   └── Dockerfile            # Dockerfile definition for building custom production images
├── 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

Create a New Project

subzero-cli provides you with a base-project command that lets you create a new project structure:

subzero base-project

? Enter the directory path where you want to create the project .
? Choose the starter kit (Use arrow keys)
❯ subzero-starter-kit (REST & GraphQL) 
  postgrest-starter-kit (REST)

After the files have been created, you can bring up your application (API). 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:

REST http://localhost:8080/rest/
GraphiQL IDE http://localhost:8080/graphiql/
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 at http://localhost:8080/graphiql/

{
  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/lua file in your project, the changes will immediately be applied.

Testing

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

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

Deployment

Contributing

Anyone and everyone is welcome to contribute.

Support and Documentation

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

License

Copyright © 2017-present 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.

StealthStartupLabs/subzero-starter-kit