RESTful API plugin for Egg.
Developing RESTful API with egg-rest is very simple. You may read JSON API spec first.
$ npm i egg-rest
Enable the rest plugin in plugin.js:
exports.rest = true;
Configure the rest plugin in config/config.default.js:
exports.rest = {
urlprefix: '/doc/api/', // Prefix of rest api url. Defaluts to /api/
authRequest: null,
// authRequest: function* (ctx) {
// // A truthy value must be returned when authentication succeeds.
// // Otherwise the client will be responded with `401 Unauthorized`
// return accessToken;
// }
// Specify the APIs for which authentication can be ignored.
// If authRequest is configured, authentication for all APIs is required by default.
authIgnores: null,
// authIgnores: {
// users: {
// show: true, // allow GET /api/users/:id to ignore authentication
// index: true,
// }
// }
};
Controllers in files matching ${baseDir}/app/apis/**.js will be loaded automatically according to routing rules.
Caution
If your RESTful API is open to public systems or websites, you should disable [ctoken] security validation, which is provided by security plugin, for your RESTful url prefix:
exports.security = {
ignore: '/doc/api/'
};
Follow the naming conventions of rails:
| method | url | file path | controller name |
|---|---|---|---|
| GET | /doc/api/{objects}[?per_page={per_page}&page={page}] | app/apis/{objects}.js | index() |
| GET | /doc/api/{objects}/:id | app/apis/{objects}.js | show() |
| POST | /doc/api/{objects} | app/apis/{objects}.js | create() |
| PUT | /doc/api/{objects}/:id | app/apis/{objects}.js | update() |
| DELETE | /doc/api/{objects}/:id[s] | app/apis/{objects}.js | destroy() |
Nesting of two layer at most is supported.
| method | url | file path | controller name |
|---|---|---|---|
| GET | /doc/api/{parents}/:parent_id/{children}/:child_id/{objects}?per_page={per_page}&page={page} | app/apis/{parents}/{objects}.js | index() |
| GET | /doc/api/{parents}/:parent_id/{children}/:child_id/{objects}/:id | app/apis/{parents}/{objects}.js | show() |
| POST | /doc/api/{parents}/:parent_id/{children}/:child_id/{objects} | app/apis/{parents}/{objects}.js | create() |
| PUT | /doc/api/{parents}/:parent_id/{children}/:child_id/{objects}/:id | app/apis/{parents}/{objects}.js | update() |
| DELETE | /doc/api/{parents}/:parent_id/{children}/:child_id/{objects}/:id[s] | app/apis/{parents}/{objects}.js | destroy() |
Example: /api/users/3/posts/1/replies/2 => params: { parent_id: 3, child_id: 2, id: 1 }. The idea is that you can can retrieve the ids from this.params,
which you get values of { users: '3', posts: '1', replies: '2' }. It matches the file path /api/users/3/posts/1/replies/2.
Note: It does not support more than three level deep nesting. Example: /api/users/3/posts/1/replies/2/answer won't match file path
apis/users/posts/replies/answer.js. Currently, it can only retrieve maximum three query parameters.
Controllers can be loaded from index.js in parent directory.
Example: /doc/api/{parents} => app/apis/{parents}/index.js
All RESTful API must and will respond data with JSON format, following the JSON API spec.
A JSON object MUST be at the root of every JSON API request and response containing data. This object defines a document’s “top level”.
A document MUST contain at least one of the following top-level members:
Primary data MUST be either:
Why should we use the 'data' field as the entry of accessing primary data, instead of respond with it directly? In same cases, such as searching API, paging meta info is required other than primary data.
Here’s how an post (i.e. a resource of type “post”) might appear in a document:
{
"data": {
"id": "1",
// ... attributes of this post
}
}
Represent the post with just an id:
{
"data": "1"
}
{
"data": [{
"id": "1"
// ... attributes of this post
}, {
"id": "2"
// ... attributes of this post
}],
"meta": {
"count": 100 // totol number of posts
}
}
Represent posts with an array of post Ids:
{
"data": ["1", "2"]
}
Four reserved fields:
GET /doc/api/{objects}[?page={page}&per_page={per_page}]GET /doc/api/users?per_page=2
Accept: application/json
Controller exports.index will be loaded automatically.
Paging params must be accessed by this.params.page and this.params.per_page.
And both of them must be numbers.
// app/apis/user.js
// routing: GET /doc/api/users
exports.index = function* (next) {
// coding as a common controller
var users = yield uic.listUser({limit: this.params.per_page});
// totol number of users
var total = yield uic.total();
// set meta info
this.meta = {
total: total
};
this.data = users;
};
200 OK: the resource exists, accessing it successfullyHTTP/1.1 200 OK
Content-Type: application/json
{
"data": [{
"id": 1024,
"name": "shaoshuai0102",
"mobile": '186xxxxxxxx'
}, {
"id": 1025,
"name": "fengmk2",
"mobile": '186xxxxxxxx'
}],
"meta": {
"total": 100000
}
}
GET /doc/api/{objects}/:idGET /doc/api/users/1024
Accept: application/json
Controller exports.show will be loaded automatically.
// app/apis/user.js
// routing: GET /doc/api/users/:id
exports.show = function* (next) {
// coding as a common controller
var user = yield uic.getUser(this.params.id);
if (!user) {
return yield* next;
}
this.data = user;
};
200 OK: the resource exists, accessing it successfullyHTTP/1.1 200 OK
Content-Type: application/json
{
"data": {
"id": 1024,
"name": "苏千",
"mobile": '186xxxxxxxx'
}
}
GET /doc/api/{objects}/:idsGET /doc/api/users/:ids, multiple ids are seperated with comma.
GET /doc/api/users/1024,10,111
Accept: application/json
Controller exports.show will be loaded automatically.
Multiple id can be accessed with this.params.ids as an array, if you want to support multiple id.
// app/apis/user.js
// routing: GET /doc/api/users/:ids
exports.show = function* (next) {
// coding as a common controller
const users = yield userService.listUsers(this.params.ids);
this.data = users;
};
200 OK: the resource exists, accessing it successfullyHTTP/1.1 200 OK
Content-Type: application/json
{
"data": [{
"id": 1024,
"name": "fengmk2",
"mobile": '186xxxxxxxx'
}, {
"id": 10,
"name": "shaoshuai0102",
"mobile": '186xxxxxxxx'
}]
}
POST /doc/api/{objects}Must be a POST request:
POST /doc/api/users
Content-Type: application/json
Accept: application/json
{
"name": "fengmk2",
"mobile": '186xxxxxxxx'
}
Controller exports.create will be loaded automatically.
// app/apis/user.js
// Routing: POST /doc/api/users
exports.create = function* (next) {
var newUser = this.params.data;
var user = yield userService.create(newUser);
this.data = user;
};
When resource document is created successfully, 201 Created is returned, with the created document as the body.
HTTP/1.1 201 Created
Content-Type: application/json
{
"data": {
"id": 1024,
"name": "fengmk2",
"mobile": '186xxxxxxxx'
}
}
PUT /doc/api/{objects}/:idMust be a PUT request.
In the example below, only mobile field is updated:
PUT /doc/api/users/1024
Content-Type: application/json
Accept: application/json
{
"mobile": '186xxxxxxxx'
}
Controller exports.update is loaded automatically.
// app/apis/user.js
// Routing: PUT /doc/api/users/:id
exports.update = function* (next) {
var user = this.params.data;
yield userService.update(user);
};
204 No Content: when an update is successful and the server
doesn’t update any attributes besides those provided,
the server MUST return 204 No Content without the document.HTTP/1.1 204 No Content
200 OK: If a server accepts an update but also changes the
resource(s) in ways other than those specified by the request
(for example, updating the updated-at attribute or a computed sha),
it MUST return a 200 OK response.
The response document MUST include a representation of the updated
resource(s) as if a GET request was made to the request URL.HTTP/1.1 200 OK
Content-Type: application/json
{
"data": {
"id": 1024,
"name": "fengmk2",
"mobile": '186xxxxxxxx'
}
}
DELETE /doc/api/{objects}/:id[s]DELETE /doc/api/users/1024
DELETE /doc/api/users/1024,100,100023
Controller exports.destroy will be loaded automatically.
Multiple id can be accessed with this.params.ids as an array, if you want to support multiple id.
// app/apis/user.js
// Routing: DELETE /doc/api/users/:id
exports.destroy = function* (next) {
yield userService.update(this.params.id);
// or `this.params.ids` for multiple id
};
204 No Content: If a server deletes the document(s) successfully, it MUST return 204 No Content.HTTP/1.1 204 No Content
An error object is a special resource, with additional information about problems encountered while performing an operation.
201 Created should be used when creating content (INSERT),202 Accepted should be used when a request is queued for background processing (async tasks),204 No Content should be used when the request was properly executed but no content was returned (a good example would be when you delete something).400 Bad Request should be used when there was an error while processing the request payload (malformed JSON, for instance).401 Unauthorized should be used when a request is not authenticiated (wrong access token, or username or password).403 Forbidden should be used when the request is successfully authenticiated (see 401), but the action was forbidden.406 Not Acceptable should be used when the requested format is not available (for instance, when requesting an XML resource from a JSON only server).410 Gone Should be returned when the requested resource is permenantely deleted and will never be available again.422 Unprocesable entity Could be used when there was a validation error while creating an object.500 Internal Server Error should be used when server unexpected error happend.A more complete list of status codes can be found in RFC2616.
Usually detailed error information will be hidden in production to prevent security issues for code leaking
Detailed error information can be found in $HOME/logs/$APPNAME/common-error.log.
HTTP/1.1 500 Server Error
{
"message": "Internal Server Error"
}
Detailed infomation will be returned in development. It's helpful when developing and debuging.
{
"message": "TypeError: foo.bar is undefined",
"stack": "TypeError: foo.bar is undefined\n at Object.checkAuth (/Users/..."
}
Ref: https://developer.github.com/v3/#client-errors
https://api.github.com/gists/df2d46e24563df97cd9b
HTTP/1.1 404 Not Found
{
"message": "Not Found",
"documentation_url": "https://developer.github.com/v3"
}
There's a problem when parsing the recieved data as JSON.
HTTP/1.1 400 Bad Request
{
"message": "Problems parsing JSON"
}
The recieved data is not a JSON object.
HTTP/1.1 400 Bad Request
{
"message": "Body should be a JSON object"
}
Param validation failed.
HTTP/1.1 422 Unprocessable Entity
{
"message": "Validation Failed",
"errors": [
{
"field": "username",
"code": "missing_field",
"message": "username required"
}
]
}
Authorization failed
$ curl -i localhost/doc/api/users/1 -u foo:bar
HTTP/1.1 401 Unauthorized
{
"message": "Bad credentials"
}
https://developer.github.com/v3/#user-agent-required
$ curl -iH 'User-Agent: ' https://api.github.com/meta
HTTP/1.0 403 Forbidden
{
"message": "Please make sure your request has a User-Agent header"
}
Rest plugin provides a way of validating request params.
For more details of validating rules, see parameter.
createRule 和 updateRule// Specify validation rules of create request
// If failed, '422' will be returned automatically
exports.createRule = {
username: 'email',
password: {
type: 'password',
compare: 're-password'
},
age: {
type: 'int',
required: false
}
};
exports.create = function* () {
var user = this.params.data;
// handle user
};
// Specify validation rules of create request
exports.updateRule = {
age: {
type: 'int',
required: false
}
};
exports.update = function* () {
};
Validation failure example:
HTTP/1.1 422 Unprocessable Entity
{
"message": "Validation Failed",
"errors": [
{
"field": "username",
"code": "invalid",
"message": "username should be an email"
},
{
"field": "password",
"code": "missing_field",
"message": "password required"
},
{
"field": "age",
"code": "invalid",
"message": "age should be an integer"
}
]
}
In most cases, the automatic way above is just fine.
But sometimes we need do the validation manualy.
So we can use this.validate(rules[, data])
var createRule = {...};
exports.create = function* () {
var user = this.params.data;
// If validation failed, status 422 will be returned
this.validate(createRule, user);
// handle user
};
If you want to add request authentication, configure it with rest.authRequest in config/config.default.js:
exports.rest = {
enable: true,
authIgnores: {
// allow users.show() and users.index() to ignore authentication
users: {
show: true,
index: true
}
},
authRequest: function* (ctx) {
if (ctx.query.private_token === 'admintoken-123') {
// If authentication succeeds, the info returned below can be accessed with `this.accessToken` in controller.
return {
name: 'admin'
};
}
// authentication failure
return null;
}
};
For user.create(), user.update() and user.destroy(), they will be invoked only after passing authentication.
Authentication failure response:
HTTP/1.1 401 Unauthorized
{
"message": "Bad credentials"
}
FAQs
Restful API plugin for egg
The npm package egg-rest receives a total of 3 weekly downloads. As such, egg-rest popularity was classified as not popular.
We found that egg-rest demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 5 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
OpenSSF has published OSPS Baseline, an initiative designed to establish a minimum set of security-related best practices for open source software projects.
Security News
Michigan TypeScript founder Dimitri Mitropoulos implements WebAssembly runtime in TypeScript types, enabling Doom to run after processing 177 terabytes of type definitions.
Security News
vlt's new "reproduce" tool verifies npm packages against their source code, outperforming traditional provenance adoption in the JavaScript ecosystem.