Plan8

GraphQL API Services Made Easy with Node.js

Plan8 is a web server and opinionated framework for building data manipulation-centric (Create Read Update Destroy) API services in Node.js for web, mobile or IoT apps.

Overview

Plan8 is built upon an ideology of a robust, scalable architecture for data storage and retrieval APIs. It is an opinionated, explicit, idiomatic and highly-extensible full-service framework that takes care of all of the hard decisions for you and your team. This allows you to focus on creating an effective product in a short timespan while minimizing technical debt.

Plan8 servers are not meant to be monoliths. They're stateless and distributed, meant to service your needs of interfacing with your data layer effortlessly. While you can output any data format with Plan8, it's recommended you offload things like static page rendering to other optimized services like CDNs.

Stateless Dogma

It's important to note that Plan8 is meant for stateless API services. This means you should not rely on memory within a specific process to serve multiple requests, and Plan8 will use process clustering (even in development) to actively discourage this practice. If you need to work with unstructured data for rapid prototyping, connect Plan8 to a PostgreSQL database and use the "JSON" field type. You'll find yourself encountering a lot of trouble if you start trying to use in-process memory across different requests.

Remember: one input, one output. Side effects dealing with model state should be managed via your Database. Plan8 should not be used for streaming (long poll) requests and the HTTP request and response objects are intentionally obfuscated.

This also means you can not rely on socket connections. If you need to incorporate realtime functionality in your application, there should be a separate server responsible for this. It can interface with your Plan8 API server and even receive events from it, but your API server should never have a stateful (prolonged) connection with any client.

Getting Started

Getting started with Plan8 is easy.

1. Download and install the newest Node 6.x version from nodejs.org
2. Open terminal, and type npm install plan8-cli -g. (If you get an error, run sudo npm install plan8-cli -g or fix permissions permanently by following these directions
3. Using your terminal, visit your projects folder. Perhaps with cd ~.
4. Run plan8 new.
5. Follow the on screen instructions, enter your new project directory and type plan8 s.

That's it! Your Plan8 webserver is up and running.

Hooking Up Your Database

Once Plan8 is up and running, it's likely that you'll want to connect your project to a database. Plan8 comes packaged with Migrations, a Query Composer and full PostgreSQL integration.

First you'll need to install PostgreSQL. OS X users, I recommend using Postgres.app for your development environment.

Once you've installed Postgres, make sure to run:

$ createuser postgres -s

To create a default postgres superuser with no password. (Default for Plan8's configuration.)

To begin using your database, start with:

$ plan8 db:create

To create the database and then,

$ plan8 db:prepare

To prepare for migrations.

From here, plan8 db:migrate runs all pending migrations and plan8 db:rollback will roll back migrations, one at a time by default.

Server Types

Plan8 works best when you follow its ideology, and that means creating a new service to solve specific Problem Domains of your application and business.

The main three suggestions are Branding Server, API Server and Application Server.

API Server

Create an API server using Plan8's Models, PostgreSQL integration, built-in JSON API formatting, and Query Composer (ORM). Bi-directional migrations are packaged with Plan8, meaning you can maintain the integrity of your data. User (including password) and OAuth AccessToken models and controllers are pre-built for you and can be added easily to your project.

Packaged with Plan8 are workers, scheduling modules, and much more for all of your data needs.

We can look at what an API Controller might look like for, say, blog posts:

class BlogPostsController extends Plan8.Controller {

  index() {

    BlogPost.query()
      .join('user')
      .join('comments')
      .where(this.params.query)
      .end((err, blogPosts) => {

        this.respond(err || blogPosts);

      });

  }

  show() {

    BlogPost.find(this.params.route.id, (err, blogPost) => this.respond(err || blogPost));

  }

  create() {

    BlogPost.create(params.body, (err, blogPost) => this.respond(err || blogPost));

  }

  update() {

    BlogPost.update(this.params.route.id, params.body, (err, blogPost) => this.respond(err || blogPost));

  }

  destroy() {

    BlogPost.destroy(this.params.route.id, (err, blogPost) => this.respond(err || blogPost));

  }

}

Beginner's Guide

You'll be able to learn more about Plan8 at plan8.io.

Documentation

Check out the website at plan8.io.

Roadmap

View the roadmap at ROADMAP.md.

Thanks for checking out Plan8!