API Core - Quick Start

This guide will help you learn API Core by creating a simple API using Express as a provider and MongoDB as model backed by the API Core framework.

Preparation and Installation

First install the dependencies and prepare the package:

$ yarn init
$ yarn add api-core api-provider-express api-modell-mongoose api-provider
$ yarn add express mongoose
$ yarn add @types/express @types/mongoose

Also create a tsconfig.json file:

{
  "compilerOptions": {
    "target": "es6",
    "outDir": "dist",
    "module": "commonjs",
    "declaration": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "removeComments": true,
    "moduleResolution": "node",
    "sourceMap": true,
    "inlineSources": true,
    "lib": ["es5", "es2015.promise" ]
  },
  "exclude": [
    "node_modules", "dist"
  ]
}

Creating the web server

To provide the to-be-created API, you will need a web server. This could be anything, from a server created using only the built in HTTP library of Node to almost any third-party (eg. Express, Koa, Ellipse). Anyway, you will need the matching API Core provider package.

In this demo we will use Express and api-provider-express.

Create the index.ts file and add the following:

import * as express from 'express';
const app = express();

app.get('/hello', (req, res) => {
    res.send('Hello World!')
});

app.listen(3333, 
    () => console.log('API Core DEMO - Listening on port 3333...'));

Now edit package.json. Add the following to specify the correct entry point and start script:

"main": "dist/index.js",
"scripts": {
  "start": "node dist"
}

It's time to test your server:

$ yarn start

Now you can navigate to http://localhost:3333/hello in a browser.

Creating the API and providing it via the server

First add our API definition after the hello edge, but before the call to listen:

const path = require('path');
import {Api} from "api-core";
import {ApiProvider} from "api-provider";

const api = new ApiProvider;

api.version('2.0')
    .edgeDir(path.join(__dirname, 'src/edges'))
//    .relationDir(path.join(__dirname, 'src/relations'))
//    .actionDir(path.join(__dirname, 'src/actions'));

Now we have an API, continue with the configuration of Express. We need to setup body parsing, handle Chrome's requests for favicon and allow access from client scripts and disable caching with the appropriate headers:

app.use(require('body-parser').json());
app.get('/favicon.ico', (req: any, res: any) => res.send(''));

app.use((req: any, res: any, next: any) => {
    //Access from any domain
    res.header('Access-Control-Allow-Origin', '*');
    res.header('Access-Control-Allow-Methods', 'GET,PUT,POST,PATCH,DELETE');
    res.header('Access-Control-Allow-Headers', 'Content-Type');
    res.header('Access-Control-Expose-Headers', 'X-Total-Count');

    //Disable cache
    res.header('Cache-Control', 'private, no-cache, no-store, must-revalidate');
    res.header('Expires', '-1');
    res.header('Pragma', 'no-cache');

    next()
});

app.options('*', (req, res) => {
    res.header('Access-Control-Allow-Origin', '*');
    res.header('Access-Control-Allow-Methods', 'GET,PUT,POST,DELETE');
    res.header('Access-Control-Allow-Headers', 'Content-Type');
    res.send();
});

Now we are ready to provide our API via Express:

import {ExpressApiRouter} from "api-provider-express";
api.provide(ExpressApiRouter).apply(app);

Before you could start the API, ypu have to create an edge first.

Creating the first edge