Have ideas to improve npm?Join in the discussion! »

    api-core
    TypeScript icon, indicating that this package has built-in type declarations

    3.0.0 • Public • Published

    API Core

    Lightweight framework for building dynamic multi-level APIs for any provider (Express, socket.io, etc.), consumable via multiple channels (HTTP, socket.io, etc.)

    GitHub license GitHub issues Build Status Coverage Status Codacy Badge

    Features

    • Dynamic model-based API routes
    • Extensible API queries with pre- and post-query steps (coming soon)
      • Transformations (via api-core-mapper or your own library)
      • Authentication, ACL (via node-acl, passport, etc.)
    • Multi level API routes (eg. /schools/42/students/3/courses)
    • Multi channel APIs (eg. consuming HTTP and socket.io via api-provider packages)
    • Multi database APIs (different database for every route, if you need)
    • Versioned APIs
    • Swagger compatibility (via api-core-mapper)

    Installation

    API Core is in beta and NOT ready for production use.

    To install the latest version, use NPM:

    $ npm install api-core

    Basics

    API Edges

    In API Core every API is built from edges. An edge defines operations and relations of a Data Model.

    Every edge provides the following operations:

    • List entries (eg. GET /students)
    • Get an entry (eg. GET /students/3)
    • Create an entry (eg. POST /students)
    • Replace/Update an entry (eg. PUT /students/3)
    • Edit an entry (eg. PATCH /students/3)
    • Remove an entry (eg. DELETE /students/3)
    • Access to operations of one-to-one relations (eg. GET /students/3/class)
    • Access to operations of one-to-many relations (eg. GET /schools/42/students/3/courses)
    • Access to custom operations (eg. PUT /students/3/rename)

    Every operation provides standard features like filtering, sorting, population and pagination.

    Also every operation is available via all enabled channels.

    So while you can list students via a HTTP request, you also can do the same via a socket.io message or any custom channel defined by you.

    API Providers

    You can use API Providers to make your API consumable via different channels.

    We have (or working on) providers for the following channels:

    • HTTP
    • Socket
      • socket.io: api-provider-socket.io (coming soon)

    Also you can implement your own API provider.

    Data Models

    Every API requires a set of data models. As with API Providers, you have a bunch of options when choosing your library for creating the models.

    We have (or working on) data model libraries for the following frameworks:

    Also you can implement your own API model library.

    Usage

    We have two working examples in the following repository, one with a local in-memory model (master branch) and one with a Mongoose model (mongodb branch).

    Working Demo: api-demo

    A complete API with 5 models and relations in 67 lines:

    import {ApiEdgeError, OneToOneRelation, OneToManyRelation, ApiEdgeQueryResponse, Api} from "api-core";
    import {MongooseModelFactory} from "api-model-mongoose";
    import {EllipseApiRouter} from "api-provider-ellipse";
    import * as mongoose from "mongoose";
    
    const Ellipse = require('ellipse'),
          app = new Ellipse;
    
    mongoose.Promise = global.Promise;
    mongoose.connect("mongodb://localhost/api-demo");
    const ObjectId = mongoose.Schema.Types.ObjectId;
    
    const studentEdge =
              MongooseModelFactory.createModel("student", "students", {
                  id: String,
                  firstName: String,
                  lastName: String,
                  email: String,
                  phone: String,
                  school: { type: ObjectId, ref: 'school' },
                  classId: { type: ObjectId, ref: 'class' }
              }),
          classEdge =
              MongooseModelFactory.createModel("class", "classes", {
                  id: String,
                  name: String,
                  semester: String,
                  room: String,
                  school: { type: ObjectId, ref: 'school' }
              }),
          courseEdge =
              MongooseModelFactory.createModel("course", "courses", {
                  id: String,
                  name: String,
                  class: { type: ObjectId, ref: 'class' },
                  courseType: { type: ObjectId, ref: 'courseType' }
              }),
          courseTypeEdge =
              MongooseModelFactory.createModel("courseType", "courseTypes", {
                  id: String,
                  name: String
              }),
          schoolEdge =
              MongooseModelFactory.createModel("school", "schools", {
                  id: String,
                  name: String,
                  address: String,
                  phone: String
              });
    
    const api10
        = new Api({name: 'test-service', version: '1.0'})
            .edge(studentEdge);
    
    const api11
        = new Api({name: 'test-service', version: '1.1'})
            .edge(studentEdge)
            .edge(classEdge)
            .edge(courseEdge)
            .edge(courseTypeEdge)
            .edge(schoolEdge);
    
    app.use(require('body-parser').json());
    
    const router = new EllipseApiRouter(api11, api10);
    router.apply(app);
    
    app.listen(8080);

    Tests

    We maintain high test coverage to provide a reliable framework for your APIs.

    To run tests, execute the following NPM commands:

    $ npm install
    $ npm test

    License

    The MIT License. Free forever. :)

    Install

    npm i api-core

    DownloadsWeekly Downloads

    28

    Version

    3.0.0

    License

    MIT

    Unpacked Size

    712 kB

    Total Files

    206

    Last publish

    Collaborators

    • avatar
    • avatar