From 608d5cd3860e67c450ef755690056a4883be7a71 Mon Sep 17 00:00:00 2001
From: Carl Bennett <carlbennettnz@gmail.com>
Date: Mon, 31 Aug 2015 11:48:06 +1200
Subject: [PATCH] Add documentation

---
 README.md | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/README.md b/README.md
index 24cdff12..15821f0a 100644
--- a/README.md
+++ b/README.md
@@ -77,6 +77,8 @@ To use this library, you describe the special behavior (if any) that resources o
 
 - <a name="before-save"></a>`beforeSave` (optional): a function called on each resource provided by the client (i.e. in a `POST` or `PATCH` request) before it's sent to the adapter for saving. You can transform the data here as necessary or pre-emptively reject the request. [Usage details](https://github.com/ethanresnick/json-api-example/blob/master/src/resource-descriptions/people.js#L25).
 
+- <a name="before-delete"></a>`beforeDelete` (optional): a function called on each resource to be deleted, allowing you to throw an error if the action is not allowed. See [Handling Errors](#handling-errors) for more information.
+
 - <a name="labels"></a>`labelMappers` (optional): this lets you create urls (or, in REST terminology, resources) that map to different database items over time. For example, you could have an `/events/upcoming` resource or a `/users/me` resource. In those examples, "upcoming" and "me" are called the labels and, in labelMappers, you provide a function that maps each label to the proper database id(s) at any given time. The function can return a Promise if needed.
 
 - <a name="parentType"></a>`parentType` (optional): this allows you to designate one resource type being a sub-type of another (its `parentType`). This is often used when you have two resource types that live in the same database table/collection, and their type is determined with a discriminator key. See the [`schools` type](https://github.com/ethanresnick/json-api-example/blob/master/src/resource-descriptions/schools.js#L2) in the example repository.
@@ -107,5 +109,31 @@ This library gives you a Front controller (shown in the example) that can handle
 
 In the example above, routing is handled with Express's built-in `app[VERB]` methods, and the three parameters are set properly using express's built-in `:param` syntax. If you're looking for something more robust, you might be interested in [Express Simple Router](https://github.com/ethanresnick/express-simple-router). For authentication, check out [Express Simple Firewall](https://github.com/ethanresnick/express-simple-firewall).
 
+## Handling Errors
+
+This library provides an error contructor and a handler that you can use to return JSON API-compliant errors to the user. For example, here is how you would handle 404s.
+
+```javascript
+var API = require("json-api");
+var APIError = API.types.Error;
+
+// Your route definitions would go here, but if none match...
+
+app.use(function(req, res, next) {
+  var err = new APIError(404, undefined, "Not Found");
+  Front.sendError(err, req, res);
+});
+```
+
+You can also throw an APIError inside `beforeSave`, `beforeRender`, and `beforeDelete` transforms to cancel the request.
+
+```javascript
+beforeDelete: function(resource, req, res, superFn) {
+  if (req.user.role !== "admin") {
+    throw APIError(403, undefined, "You are not allowed to delete this resource.");
+  }
+}
+```
+
 ## Database Adapters
 An adapter handles all the interaction with the database. It is responsible for turning requests into standard [`Resource`](https://github.com/ethanresnick/json-api/blob/master/src/types/Resource.js) or [`Collection`](https://github.com/ethanresnick/json-api/blob/master/src/types/Collection.js) objects that the rest of the library will use. See the built-in [MongooseAdapter](https://github.com/ethanresnick/json-api/blob/master/src/db-adapters/Mongoose/MongooseAdapter.js) for an example.