README

lucid-restful

Adonis Provider/Middleware package to create RESTful API for Lucid ORM.

Setup:

Install required packages

adonis install @adonisjs/fold --yarn
yarn add lucid-restful
or
adonis install @adonisjs/fold
npm install lucid-restful

Edit /start/app.js

const providers = [
  ...
  'lucid-restful/providers/LucidRestfulProvider'
]

Edit /start/routes.js

Route.restful('/restapi')

Methods:

The middleware is schema-agnostic, allowing any json document to be persisted and retrieved from database.

Route	Method	Notes
/:collection	GET	Search the collection (Filters: under development)
/:collection	POST	Create a single document
/:collection	PUT	Method Not Allowed
/:collection	DELETE	Method Not Allowed
/:collection/:id	GET	Retrieve a single document
/:collection/:id	POST	Method Not Allowed
/:collection/:id	PUT	Update a document
/:collection/:id	DELETE	Remove a single document

/:collection/count	GET	Count the collection

/:collection	PATCH	Method Not Allowed
/:collection/:id	PATCH	Undeveloped Method

Get examples	Notes
/post	List all posts
/post/1	Retrieve post with id 1
/post?id>10&id<100	List posts id between 11 and 100
/posts?with=comments	List posts with comments
/posts?with=comments(post_id,body)	List posts with comments and selected columns
/posts/1?with=comments	Retrieve post 1 with comments
/posts?order=-title	List posts sorted by title desc
/posts?page=2&limit=100	List from 101 to 200
/post?!title	List posts if title IS NULL
/post?title	List posts if title IS NOT NULL

API

Querying documents

The query API (GET /:collection) uses a robust query syntax that interprets comparision operators (=, !=, >, <, >=, <=) in the query portion of the URL using.

GET example

For example, the URL https://localhost/restapi/users?name=John&age>=21 would search the User collection for any entries that have a name of "John" and an age greater than or equal to 21.

[
  { id: '1', name: 'John', age: 21 }
]

Pager and Order by

Paginate

URL https://localhost/restapi/users?page=1&limit=10

Ascending

URL https://localhost/restapi/users?order=name&page=1&limit=10

Descending

URL https://localhost/restapi/users?order=-name

q Search

Use the q parameter to perform a substring search specified in the 'qSearchFields' attribute of the model.

URL https://localhost/restapi/users?q=John%

[
  { id: '1', name: 'John', age: 21 }
  { id: '1', name: 'Edward', lastName: 'Johnathan', age: 21 }
]

class User extends Model {
...
}

User.qSearchFields = ['name', 'lastName']

POST example

Documents are saved using the Lucid ORM save function. An example post return the document saved:

URL: https://localhost/restapi/users Data: { name: 'Peter', age: 19 } Result:

{
  id: 2,
  name: 'Peter',
  age: 19
}

PUT example

Documents are saved using the Lucid ORM save function.

URL: https://localhost/restapi/users/2 Data: { age: 17 } Result:

{
  id: 2,
  name: 'Peter',
  age: 17
}

Count example

URL: https://localhost/restapi/users/count?age>=18 Result

{ count: 2 }

Custom filters

This midlaware add before paginete suporte in all restful calls.

class Post extends Model {
  static boot () {
    super.boot()

    this.addHook('beforePaginate', async (query, request) => {
        let params = request.get()
        
        if (params.customfilter) {
            query.where(..., ...)
            
            delete params.customfilter
        }
    })
  }
  ...
}

With suporte / Eager loading

To get a relation to another model using "with", just use the "with" parameter as an examples:

URL: https://localhost/restapi/comment?with=post Result:

[{ 
    id: 1,
    body: 'Lorem ipsum',
    post_id: 1,
    post: {
        id: 1,
        title: 'Lipsum',
        body: 'It`s awesome',
        ...
    } 
}]

URL: https://localhost/restapi/post?with=comments Result:

[{
    id: 1,
    title: 'Lipsum',
    body: 'It`s awesome',
    comments: [{
        id: 1,
        body: 'Lorem ipsum',
        post_id: 1,
        ...
    }]
}]

Select With columns

if you need to select some columns in the related table. Just indicate the columns in parentheses as below:

URL: https://localhost/restapi/post?with=comments(post_id,body) Result:

[{
    id: 1,
    title: 'Lipsum',
    body: 'It`s awesome',
    comments: [{
        post_id: 1,
        body: 'Lorem ipsum',
    }]
}]

Note: It is necessary to inform the join columns.

Fillable Properties

The fillable property specifies which attributes should be mass-assignable. This can be set at the model class.

class Post extends Model {
  ...
}
Post.fillable = ['title', 'body']

Cascade Save

class Post extends Model {
  ...
  comments () {
    return this.hasMany('App/Models/Comment')
  }
}
Post.cascadeFillable = ['comments']

URL: https://localhost/restapi/post Data: { title: 'Lipsum', comments: [{ body: 'Lorem ipsum' }] } Result:

[{
    id: 2,
    title: 'Lipsum',
    comments: [{
        id: 3,
        body: 'Lorem ipsum',
        post_id: 2,
    }]
}]

Validator

To validate the requisitions, add in the app/Validators/ folder the validators with the same name as the templates. Requires @adonisjs/validator to enable.

app/Models/Post.js

app/Validators/Post.js

Aggregate function suporte

class Post extends Model {
  ...
  commentsCount () {
    return this.belongsTo('App/Models/Comment')
      .groupBy('post_id')
      .select('post_id')
      .select(Database.raw('count(id)'))
  }  
}

URL: https://localhost/restapi/post?with=commentsCount Result:

[{
    id: 2, title: 'Lipsum',
    commentsCount: { post_id: 2, count: 1 }
},{
    id: 3, title: 'Lorem',
    commentsCount: { post_id: 3, count: 13 }
}]

Configuration

Midleware properties

Route	Type	Default	Notes
modelfolder	String	App/Models	Change Models Folder

Custom controller

if you need to customize the data output.

Route.resource('/restapi/:collection/:id*', '_Custom_Controller_').middleware(['lucid-restful'])

Usage no npm install needed!