Starter Kit and tooling for authoring GraphQL/REST API backends with subZero
Branch: master
Clone or download

README.md

subZero GraphQL/REST API Starter Kit

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

subZero Starter Kit

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
✓ Custom PostgREST binary that creates prepared statements instead of inline queries
✓ Live events (with authentication/authorization) through RabbitMQ WebSTOMP plugin

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
│   ├── lualib
│   │   └── user_code         # Application Lua code
│   ├── nginx                 # Nginx files
│   │   ├── conf              # Configuration files
│   │   └── html              # Static frontend files
│   ├── Dockerfile            # Dockerfile definition for production
│   └── entrypoint.sh         # Custom entrypoint
├── 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:

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

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.