adonis-api-resources

AdonisJS API resources

Description

Provides a transformation layer between models and actual API endpont responses in JSON format.

Setup

Install the package:

npm install adonis-api-resources

Configure the package:

node ace configure adonis-api-resources

Generate a new resource (i.e. for a user):

node ace make:resource user

Import your generated resource before using it, i.e. in a controller:

import UserResource from '#resources/user_resource'

Remove old endpoint return declaration:

return user

Use the your generated resource instead:

return new UserResource(user).refine()

redefine() and refine() - manually defined map

redefine() modifies a model or array of models according to your custom map defined in resource file. Used along with get() method, which indicates that data processing is done and provides the result. You can also use refine(), which is an alias of redefine().get(), see example below.

Edit newly generated app/resources/user_resource.ts to create output you need. This example shows how you may output user's full name even if your implementation of user model has separate fields for the first and last names:

...
  return {
    full_name: data.firstName + ' ' + data.lastName,
  }
...

You may also use arrays of models with resources:

return new UserResource(users).refine()

Output examples

Model:

{
  "full_name": "John Doe"
}

Array of models:

[
  {
    "full_name": "John Doe"
  },
  {
    "full_name": "Jane Doe"
  }
]

paginate() and refinePaginate()

In case you are dealing with not paginateable array you can still create pagination using this extension. refinePaginate() is an alias of redefine().paginate(), see examples below:

return new UserResource(users).refinePaginate(page, limit)
return new UserResource(users).redefine().paginate(page, limit)

Arguments:

page - number of page to show (optional, default value: 1)
limit - items per page (optional, default value: 10)

pick()

No map definition is needed, once you only want to pick a few values of the object and leave other values behind. Examples:

return new UserResource(users).pick('firstName').get()
return new UserResource(users).pick('firstName', 'lastName', 'email').paginate(1, 20)

omit()

No map definition is needed, once you only want to exclude a few values from the object. Examples:

return new UserResource(users).omit('id').paginate()
return new UserResource(users).omit('createdAt', 'updatedAt').get()

get()

get() finalizes data processing. While pick(), omit() and redefine() modify data, trailing get() or paginate() is needed to complete the response. This requirement is not applied to refine() and refinePaginate()

Lucid pagination support

Lucid offset-based pagination is supported.