Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/restberry/restberry
Framework for setting up RESTful JSON APIs with NodeJS.
https://github.com/restberry/restberry
javascript nodejs npm restberry
Last synced: about 1 month ago
JSON representation
Framework for setting up RESTful JSON APIs with NodeJS.
- Host: GitHub
- URL: https://github.com/restberry/restberry
- Owner: restberry
- Created: 2014-01-21T20:20:12.000Z (almost 11 years ago)
- Default Branch: master
- Last Pushed: 2016-11-09T12:26:41.000Z (about 8 years ago)
- Last Synced: 2024-04-14T12:29:09.338Z (9 months ago)
- Topics: javascript, nodejs, npm, restberry
- Language: JavaScript
- Homepage:
- Size: 278 KB
- Stars: 116
- Watchers: 10
- Forks: 10
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
[](http://restberry.com)
[](http://twitter.com/thematerik)
[](https://www.npmjs.com/package/restberry)
[](https://www.npmjs.com/package/restberry)
[](https://travis-ci.org/materik/restberry)
> Restberry works with both Express and Restify!
Framework for setting up RESTful JSON APIs with NodeJS. Define your models and setup CRUD API
calls without needing to write any code (see [Usage](#usage)). All API calls will handle
and identify issues and throw necessary HTTP responses and easy to debug error
responses. Restberry also handles authentication and permission checks and
throws appropriate errors.
## Install
```bash
npm install restberry
```
## Example
See [``example``](/example) for a detailed documentation of how you setup a Restberry app.
## Usage
```javascript
var restberry = require('restberry');
restberry
.config({
apiPath: '/api/v1',
port: 5000,
})
.listen();
restberry.model('Foo')
.schema({
name: {type: String},
})
.routes
.addCreateRoute()
.addReadManyRoute();
restberry.model('Bar')
.schema({
foo: {type: restberry.odm.ObjectId, ref: 'Foo'},
name: {type: String},
})
.routes
.addCRUDRoutes({
parentModel: 'Foo',
});
```
**NOTE:** By default, Restberry integrates with ExpressJS and Mongoose but it
can be hooked up with other packages. See more usages in the tests and dependent
packages like:
- [`restberry-express`](https://github.com/materik/restberry-express)
- [`restberry-mongoose`](https://github.com/materik/restberry-mongoose)
- [`restberry-restify`](https://github.com/materik/restberry-restify)
## Response examples
All these responses below are automatically handled without needing to write any
additional code.
* **200** OK
```bash
2014-05-11T11:55:53.916Z|172.16.122.129|GET|/api/v1/foos/536f6549e88ad2b5a71ffdc6|<{}>
2014-05-11T11:55:53.920Z|172.16.122.129|200|<{
"foo": {
"href": "/api/v1/foos/536f6549e88ad2b5a71ffdc7",
"id": "536f6549e88ad2b5a71ffdc7",
"name": "test"
}
}>
```
* **201** CREATED
```bash
2014-05-11T11:55:54.210Z|172.16.122.129|POST|/api/v1/foos|<{
"name": "test"
}>
2014-05-11T11:55:54.210Z|172.16.122.129|201|<{
"foo": {
"href": "/api/v1/foos/536f654ae88ad2b5a71ffdcb",
"id": "536f654ae88ad2b5a71ffdcb",
"name": "test"
}
}>
```
* **204** NO CONTENT
```bash
2014-05-11T11:55:52.575Z|172.16.122.129|DELETE|/api/v1/foos/536f6548e88ad2b5a71ffdb7|<{}>
2014-05-11T11:55:52.579Z|172.16.122.129|204|
```
**NOTE:** See [`restberry-errors`](https://github.com/materik/restberry-errors) for possible error responses.
## Authentication
See [`restberry-passport`](https://github.com/materik/restberry-passport).
## Routing
```javascript
restberry.model('Foo')
.routes
.addCreateRoute() // POST /foos
.addDeleteRoute() // DELETE /foos/:id
.addPartialUpdateRoute() // POST /foos/:id
.addReadManyRoute() // GET /foos
.addReadRoute() // GET /foos/:id
.addUpdateRoute() // PUT /foos/:id
.addCRUDRoutes() // All of the above...
```
Handle action query strings like this:
```javascript
restberry.model('Foo')
.routes
.addPartialUpdateRoutes({
actions: {
build: function(req, res, next) {
...
}, // POST /foos/:id?action=build
},
})
```
And Handle parent models like this:
```javascript
restberry.model('Foo')
.routes
.addCreateRoutes({
parentModel: restberry.model('Bar'),
}) // POST /bars/:id/foos
```
**NOTE:** this can only be applied to ReadMany and Create.
You can also create custom routes. The possible configurations you can make are:
```javascript
restberry
.routes
.addCustomRoutes({
action: function(req, res, next) {
...
},
apiPath: '/api/v1', // overrides the one set on Restberry
actions: { },
loginRequired: false, // should authenticate the request
method: 'GET', // choices: DELETE, GET, POST, PUT
parentModel: restberry.model('Bar'),
path: '/path/to', // the path of the route, will append apiPath
postAction: function(json, req, res, next) {
...
}, // will be executed after action
preAction: function(req, res, next) {
...
}, // will be executed before action
verbose: false, // will print the API call on initiation
})
```
**NOTE:** you can set these properties to all the predefined API definitions,
you won't be able to override `action` however.
## Run the tests
```bash
npm test
```
## Further reading
I have written an article series on RESTful JSON API design which this package is base upon, you can find the three parts here: [part 1](http://materik.tumblr.com/post/98324672516/restful-json-api-design-part-1), [part 2](http://materik.tumblr.com/post/99806761591/restful-json-api-design-part-2) and
[part 3](http://materik.tumblr.com/post/101938795476/restful-json-api-design-part-3).
## Contact
I'm really interested to here what you guys think of Restberry, especially if
you have any suggestions to improve the package. Please contact me at
[email protected].