This library complements rest-sugar by providing revisioning. While it adds some overhead it makes it possible to create wikis and such with a nice REST backend.
As there is no standard way to implement revisioning on top of a REST scheme, I ended up making my own interpretation of the subject.
The following urls contain a prefix given at init.
- GET /? (ie. /api/v1) -> API metadata (ie. schema and help)
- GET /<api> -> Get all
- GET /<api>?name=foobar -> Get all with the matching name
- GET /<api>?limit=25&offset=50 -> Get with pagination
- GET /<api>/count -> Get count
- GET /<api>?fields=name,color -> Get name and color fields only
- POST /<api>?name=foobar -> Create new item with the given name
- PUT /<api> -> Disallowed, gives 403 error
- DELETE /<api> -> Disallowed, gives 403 error
Note that it is possible to mix and match various GETs above. The API above is what you get by using rest-sugar. There are some differences in the way you deal with CRUD. While the operations are the same, there are some extra considerations to keep in mind. The following urls operate on a specific resource (ie. /<api>/<id>).
- GET /<api>/<id> -> Get resource matching to the id. Returns the latest "active" revision.
- POST /<api>/<id> -> Disallowed, gives 403 error
- PUT /<api>/<id>?name=joe -> Updates the content of the given resource with the given field data. Creates a new revision.
- DELETE /<api>/<id> -> Deletes the given resource by setting "active" state of all its revisions to zero. Returns an empty structure if successful.
In addition there is a revision related API as described below:
- GET /<api>/<id>/revisions Returns all revisions related to a certain resource regardless of their state. If you want just "active" ones, use a filter (ie. active=1).
- PUT /<api>/<id>/revisions/<id>?active=0 Makes the revision and all following it inactive.
- PUT /<api>/<id>/revisions/<id>?active=1 Makes the revision and all before it active.
DELETE and POST have been disallowed for revisions and give 403 error accordingly.
Note that it is possible to emulate POST, PUT and DELETE via GET by using a query (ie. method=post).
In case you want to use some authentication method (preferable!), you may provide a custom auth handler for the init. It wraps each call in the API except for the metadata one. It's signature is auth(fn) meaning you are supposed to call fn in case auth has been made properly. The default implementation just passes everything through.
rest-revision-sugar is available under MIT. See LICENSE for more details.