Meituan-Dianping/koa-restql

Name: koa-restql

Owner: ????

Description: Build real RESTful APIs without writing one line of code.

Created: 2016-07-26 08:47:56.0

Updated: 2018-05-23 11:27:13.0

Pushed: 2016-11-03 11:07:23.0

Homepage: null

Size: 277

Language: JavaScript

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

koa-restql

Build real RESTful APIs without writing one line of code. Cool, right?

Now it works perfectly with MySQL.

[toc]

Installation

koa-restql requires node v6.0.0 or higher for (partial) ES2015 support.

install --save koa-restql

Usage

t koa     = require('koa')
t RestQL  = require('koa-restql')

app = koa()
restql = new RestQL(sequelize.models) // Build APIs from `sequelize.models`
use(restql.routes())

How to request real RESTful APIs

Basic

/user

If you just have one database table and sequelize model both named user, just choose the right HTTP method to visit path as exactly same name as it.

Using querystring in your url can add condition or limit for the request. For more details, read about querystring.

List

• Request

  /user
  

• Response

  /1.1 206 Partial Content
  nge: items 0-2/10
  

  
  
  
  "id": 1,
  "name": "Li Xin"
  
  
  "id": 2,
  "name": "Zhang Chi"
  
  
  

  Note:

  • Request for a list will always respond an array.
  • This response example include necessary HTTP headers to explain how Partial Content works. If the response was just part of the list, the API would like to response HTTP status code 206.

Single

• Request

  /user/1
  

• Response

  
  d": 1,
  ame": "Li Xin"
  
  

  Note: Request path with id will always respond an object.

Association

1:1

To define an 1:1 association with sequelize, use model.hasOne() or model.belongsTo().

• Request

  /user/1/profile
  

• Response

  
  d": 1,
  ser_id": 1,
  ite": "https://github.com/crzidea"
  
  

  Note: This example is for hasOne(). If the profile was an association defined with belongTo(), there should not be user_id field.

1:N

To define an 1:N association with sequelize, use model.belongsTo().

List

• Request

  /user/1/messages
  

• Response

  
  
  "id": 1,
  "content": "hello"
  
  
  "id": 2,
  "content": "world"
  
  
  

Single

• Request

  /user/1/messages/2
  

• Response

  
  d": 2,
  ontent": "world"
  
  

N:M

To define an N:M association with sequelize, use model.belongsToMany().

Basicly, you can use the same way to request n:n association as 1:N association. The difference is response.

• Request

  /user/1/friends/2
  

• Response

  
  d": 2,
  ame": "Zhang Chi",
  riendship": {
  "id": 1,
  "user_id": 1,
  "friend_id": 2
  
  
  

  Note: RestQL will respond the target model with another model referred through option.

Another noticeable problem is, you can not do the following query with association path although it is supported by sequelize:

ls.user.findAll(

include: models.user.association.friends

But, fortunately, you can implement the query with querystring like this:

/user?_include%5B0%5D=friends

Read more.

CRUD

RestQL could do all CRUD operations for you. Just choose the right HTTP method to access either the resource or the association path.

Supported HTTP verbs:

HTTP verb | CRUD | ——— | ————- | GET | Read | POST | Create | PUT | Create/Update | DELETE | Delete |

Supported HTTP method with body:

HTTP verb | List | Single | ——— | ———— | —— | POST | Array/Object | × | PUT | Array/Object | Object |

• List path examples:
  • /resource
  • /resource/:id/association, association is 1:n relationship
  • /resource/:id/association, association is n:m relationship
• Single path examples:
  • /resource/:id
  • /resource/:id/association, association is 1:1 relationship
  • /resource/:id/association/:id, association is 1:n relationship
  • /resource/:id/association/:id, association is n:m relationship

Note: PUT method must be used with unique key(s), which means you can not use PUT method with a request body without an unique key.

To use POST or PUT method, you should put data into request body. Example:

 /user


ame": "Li Xin"

querystring

It's strongly recommended that use qs to stringify nesting querystrings. And this document will assume you will use qs to stringify querystring from JavaScript object.

Example:

tringify({a: 1, b:2}) // => a=1&b=2

To understand RestQL querystring, there are only 3 rules:

• Every keys in querystring not start with _, will be directly used as where option for sequelize#query(). Example:

  uery
  
  me: "Li Xin"
  
  ption for sequelize
  
  ere: {
  name: "Li Xin"
  
  
  

• Every keys in querystring start with _, will be directly used as sequelize#query().

  uery
  
  imit: 10
  
  ption for sequelize
  
  mit: 10
  
  

• include option for sequelize#query() should be passed as String of association name.

  uery
  
  nclude: ['friends']
  
  ption for sequelize
  
  clude: [
  models.user.association.friends
  
  
  

Sometimes, you want modify query in your own middleware. To do so, you should modify this.restql.query instead of this.request.query or this.query, because the query MUST be parsed with the package qs, not querystring (which is default package of koa).

Access Control

There are at least 2 ways to implement the Access Control:

1. Add another middleware before request be handled by RestQL.
2. Add options on sequelize#model#associations, RestQL will handle the options.

This document will only talk about the 2nd way. And the option was only support with associations, not with models.

1. To specify which association should not be accessed by RestQL, add ignore option. Example:

   ls.user.hasOne(
   dels.privacy,
   
   restql: {
     ignore: true
   }
   
   
   

2. To specify an association should not be accessed by specific HTTP method, add the method to ignore as an array element. Example:

   ls.user.hasOne(
   dels.privacy,
   
   restql: {
     ignore: ['get']
   }
   
   
   

Running tests

test

License

MIT