API Reference

Typescript REST API Builder

The Typescript Express.js REST API builder is a utility that can be used to prepare the boilerplate for Cofor.io-compatible backend applications.

The Cofor.io Typescript REST API builder is included in the Cofor.io Node.js Product SDK and can be used to setup boilerplate code for an Express.js API using Typescript which uses Cofor.io for authentication, authorization, membership, and billing functionality.

👍

Modern Technology Stack

APIs built using the Cofor.io Typescript API builder uses:

  • Typescript - programming language
  • Express.js - API server
  • Mongoose - MongoDB database driver
  • AWS S3 - File storage
  • SendGrid - Email client
  • Cofor.io - Productization functionality

Installation

The Cofor.io Typescript API builder is a script included with the Cofor.io Node.js Product SDK. Install the Product SDK using npm or yarn

npm install @inventives/coforio-sdk
yarn add @inventives/coforio-sdk

Creating a Typescript API

To create an API using the builder, run the script:

cd /path/to/new/project
cio-project init $PROJECT_NAME

Make sure you set your Cofor.io product ID and key in the .env file.

Create a REST Resource Group

A REST resource includes a blank database schema, model and the following endpoints:

  • GET /{resource} - lists all resources of the group. You can pass in query parameters skip and count for pagination.
  • POST /{resource} - creates a resource with the request body
  • GET /{resource}/{id} - gets the resource with identifier: id
  • PATCH /{resource}/{id} - updates the resource with the request body (diff)
  • DELETE /{resource}/{id} - deletes the resource

Run the following command to create a resource group:

cio-project new-resource $MODEL_NAME $API_PATH [...options]

The $MODEL_NAME variable is the name of the database model, which should also be the name of the resource group. The $API_PATH variable is the path to the endpoint on the API.

For example, if I wanted to create a Document resource group, I could run:

cio-project new-resource Document /v1/documents

This would create the following endpoints:

  • GET /v1/documents
  • POST /v1/documents
  • GET /v1/documents/{id}
  • PATCH /v1/documents/{id}
  • DELETE/v1/documents/{id}

The Mongoose Model will be called Document and the MongoDB collection will be called 'documents' (lower-case plural).

By default, all endpoints will only be open to valid members. Use the custom options defined below to set authorization policies for the group.

Authorization Options

  • -o or -open makes the resource endpoints public. Authorization headers are not needed for these endpoints.
  • -a $ACCESS_LEVEL or -access_level $ACCESS_LEVEL makes the resource endpoints only accessible to those with at least the specified access level or higher. $ACCESS_LEVEL must be one of member, admin, or owner.
  • -t $TEAM_SCOPES or -team_scopes $TEAM_SCOPES makes the resource endpoints only accessible to users of a team that have the required team scopes. The $TEAM_SCOPES argument is a comma-separated (no-space!) list of scopes required. For example -t ENTERPRISE,DEV would require the team scopes ENTERPRISE and DEV to be present on a team to have access to the REST resource.
  • -m $MEMBER_SCOPES or -member_scopes $MEMBER_SCOPES makes the resource endpoints only accessible to members that have the required membership scopes. The $MEMBER_SCOPES argument is a comma-separated (no-space!) list of scopes required. For example -t SUPER_ADMIN would require the member to have the scope SUPER_ADMIN to access the REST resource.

👍

Customize as you need!

You can always edit the generated boilerplate files and customize the authorizations or anything else about the code as needed!!

Create a Database Schema/Model Definition

You can just create a blank database schema/model definition using the command:

cio-project new-schema $MODEL_NAME

Create a custom endpoint in a resource group

You can create a blank endpoint for a resource using the command:

cio-project new-endpoint $TYPE $API_PATH [...options]

This will create a new endpoint in the path provided of the given type: $TYPE. The type can be one of GET, POST, PATCH, DELETE, or PUT. You may use any of the authorization options specified in the Create a REST Resource Group section.

For example, running the following command after creating the Document resource in the above example:

cio-project new-endpoint PUT /v1/documents/upload

Would result in creation of the endpoint /v1/documents/upload as a PUT endpoint that only members of a valid team can access.

Run your API for development

Once you add in the functionality to the boilerplate code, you can install the dependencies and run your API using:

npm install
npm run dev

Build and deploy your API

A Dockerfile is provided in your project directory which can be used to deploy your application. Just build that and you're all set!

docker build -t $PROJECT_NAME:latest .

A bitbucket-pipelines.yml file is also provided with branch-specific builds for a development environment (dev branch) and production environment (production branch) if you use Cycle.io for Container Orchestration. Create a Cycle.io pipeline for the build/reimage and set the following environment variables on your Bitbucket account to use it:

  • CYCLE_HUB_ID
  • CYCLE_API_KEY
  • CYCLE_PIPELINE_DEV
  • CYCLE_PIPELINE_PRODUCTION