Resources
Well-defined artifacts that are accessible
In simple terms, a resource is an artifact managed by the application that has a unique id. The resource is expected to support the following actions:
- create
- retrieve
- update
- delete
In Blueprint, we consider resources to be first-class entities because implementing resource-like behavior is quite common. For example, the message example we used to discuss both routers and controllers implemented the create and retrieve actions. We were just missing the update and delete action. One thing you will notice over time is that you will implement behavior similar to the message example each time you need to interact with a entity managed application. Blueprint therefore wants to minimize the amount of code you must reinvent—thereby improving productivity and reduce potential errors.
You define a resource by first binding a resource to path in the router. Then, you implement the corresponding resource controller.
You declare a resource path using the
resource keyword. As shown in the example below, we are declaring the /messages path as a resource path. As part of the declaration, we specify what controller the resource path should use to create its complete routes.app/routers/message.js
const { Router } = require ('@onehilltech/blueprint');
module.exports = Router.extend ({
specification: {
'/messages': {
resource: { controller: 'message' }
}
}
});
When you declare a resource path, it will automatically define the following routes relative to the resource path.
Method | Action | Path | Examples | Description |
POST | create | / | /messages | Create a one or more resources |
GET | getAll | / | /messages | Query the resources |
GET | getOne | /:rcId | /messages/:messageId | Get a single resource |
PUT | update | /:rcId | /messages/:messageId | Update an existing resources |
DELETE | delete | /:rcId | /messages/:messageId | Delete a single resource |
GET | count | /count | /messages/count | Query the number of resources |
By default, we do not automatically define a route for deleting all the resources.
You may want to restrict what routes are available to a resource. For example, you prohibit directly creating a resource because it is created someone where else in the application. Likewise, you may prohibit a resource from being able to be deleted.
When you define a resource path, you can use the
allow or deny keyword to permit or prohibit actions on the resource, respectively. If you use the allow keyword, then all resource actions are prohibited except the ones listed. Likewise, if you use the deny keyword, then all resource actions are permitted except for the ones listed.Here is an example that restrict what actions are permitted.
const { Router } = require ('@onehilltech/blueprint');
module.exports = Router.extend ({
specification: {
'/messages': {
resource: {
controller: 'message',
allow: ['getOne', 'getAll']
}
}
}
});
Likewise, here is another example illustrating what actions are not permitted.
const { Router } = require ('@onehilltech/blueprint');
module.exports = Router.extend ({
specification: {
'/messages': {
resource: {
controller: 'message',
deny: ['create', 'delete', 'update']
}
}
}
});
You implementing the resource controller the same way you implement any other controller. But, instead of extending the
Controller class, you extend the ResourceController class. The ResourceController class has a methods that correspond to each action listed in the table above. You just have to provide the corresponding implementation for each supported action.The
ResourceController class has empty methods for each action by design. This is because the implementation of a resource controller depends heavily on where the data is persisted. For example, a in-memory resource controller will store its resources in memory. Whereas, a MongoDB resource controller will persists is resources to a MongoDB database. We therefore recommend that you leverage a domain-specific resource controller since it will provide a default implementation for each action while giving you the ability to customize it accordingly.Last modified 4yr ago