From 471734e6d37fe25ac191736880543544f8de7856 Mon Sep 17 00:00:00 2001 From: Robert Curry Date: Mon, 4 Mar 2013 09:28:24 +1300 Subject: [PATCH] Move documentation into separate docs folder --- README.md | 68 ++--------------------------------------- docs/_manifest_exclude | 0 docs/en/index.md | 69 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 71 insertions(+), 66 deletions(-) create mode 100644 docs/_manifest_exclude create mode 100644 docs/en/index.md diff --git a/README.md b/README.md index 1fb7d70..618a94c 100644 --- a/README.md +++ b/README.md @@ -13,70 +13,6 @@ applications. * SilverStripe 3.0 or newer -## Configuration +## Configuration and Usage -Enabling restful access on a model will also enable a SOAP API, see `SOAPModelAccess`. - -Example DataObject with simple api access, giving full access to all object properties and relations, -unless explicitly controlled through model permissions. - - class Article extends DataObject { - static $db = array('Title'=>'Text','Published'=>'Boolean'); - static $api_access = true; - } - -Example DataObject with advanced api access, limiting viewing and editing to Title attribute only: - - class Article extends DataObject { - static $db = array('Title'=>'Text','Published'=>'Boolean'); - static $api_access = array( - 'view' => array('Title'), - 'edit' => array('Title'), - ); - } - -## Supported operations - - - `GET /api/v1/(ClassName)/(ID)` - gets a database record - - `GET /api/v1/(ClassName)/(ID)/(Relation)` - get all of the records linked to this database record by the given reatlion - - `GET /api/v1/(ClassName)?(Field)=(Val)&(Field)=(Val)` - searches for matching database records - - `POST /api/v1/(ClassName)` - create a new database record - - `PUT /api/v1/(ClassName)/(ID)` - updates a database record - - `PUT /api/v1/(ClassName)/(ID)/(Relation)` - updates a relation, replacing the existing record(s) (NOT IMPLEMENTED YET) - - `POST /api/v1/(ClassName)/(ID)/(Relation)` - updates a relation, appending to the existing record(s) (NOT IMPLEMENTED YET) - - - DELETE /api/v1/(ClassName)/(ID) - deletes a database record (NOT IMPLEMENTED YET) - - DELETE /api/v1/(ClassName)/(ID)/(Relation)/(ForeignID) - remove the relationship between two database records, but don't actually delete the foreign object (NOT IMPLEMENTED YET) - - POST /api/v1/(ClassName)/(ID)/(MethodName) - executes a method on the given object (e.g, publish) - -## Search - -You can trigger searches based on the fields specified on `DataObject::searchable_fields` and passed -through `DataObject::getDefaultSearchContext()`. Just add a key-value pair with the search-term -to the url, e.g. /api/v1/(ClassName)/?Title=mytitle. - -## Other url-modifiers - -- `&limit=`: Limit the result set -- `&relationdepth=`: Displays links to existing has-one and has-many relationships to a certain depth (Default: 1) -- `&fields=`: Comma-separated list of fields on the output object (defaults to all database-columns). - Handy to limit output for bandwidth and performance reasons. -- `&sort=&dir=` -- `&add_fields=`: Comma-separated list of additional fields, for example dynamic getters. - -## Access control - -Access control is implemented through the usual Member system with Basicauth authentication only. -By default, you have to bear the ADMIN permission to retrieve or send any data. -You should override the following built-in methods to customize permission control on a -class- and object-level: - -- `DataObject::canView()` -- `DataObject::canEdit()` -- `DataObject::canDelete()` -- `DataObject::canCreate()` - -See `DataObject` documentation for further details. - -You can specify the character-encoding for any input on the HTTP Content-Type. -At the moment, only UTF-8 is supported. All output is made in UTF-8 regardless of Accept headers. \ No newline at end of file +See the documentation in [/docs/en/index.md](docs/en/index.md) diff --git a/docs/_manifest_exclude b/docs/_manifest_exclude new file mode 100644 index 0000000..e69de29 diff --git a/docs/en/index.md b/docs/en/index.md new file mode 100644 index 0000000..ecc5846 --- /dev/null +++ b/docs/en/index.md @@ -0,0 +1,69 @@ +# SilverStripe RestfulServer Module + +## Configuration + +Enabling restful access on a model will also enable a SOAP API, see `SOAPModelAccess`. + +Example DataObject with simple api access, giving full access to all object properties and relations, +unless explicitly controlled through model permissions. + + class Article extends DataObject { + static $db = array('Title'=>'Text','Published'=>'Boolean'); + static $api_access = true; + } + +Example DataObject with advanced api access, limiting viewing and editing to Title attribute only: + + class Article extends DataObject { + static $db = array('Title'=>'Text','Published'=>'Boolean'); + static $api_access = array( + 'view' => array('Title'), + 'edit' => array('Title'), + ); + } + +## Supported operations + + - `GET /api/v1/(ClassName)/(ID)` - gets a database record + - `GET /api/v1/(ClassName)/(ID)/(Relation)` - get all of the records linked to this database record by the given reatlion + - `GET /api/v1/(ClassName)?(Field)=(Val)&(Field)=(Val)` - searches for matching database records + - `POST /api/v1/(ClassName)` - create a new database record + - `PUT /api/v1/(ClassName)/(ID)` - updates a database record + - `PUT /api/v1/(ClassName)/(ID)/(Relation)` - updates a relation, replacing the existing record(s) (NOT IMPLEMENTED YET) + - `POST /api/v1/(ClassName)/(ID)/(Relation)` - updates a relation, appending to the existing record(s) (NOT IMPLEMENTED YET) + + - DELETE /api/v1/(ClassName)/(ID) - deletes a database record (NOT IMPLEMENTED YET) + - DELETE /api/v1/(ClassName)/(ID)/(Relation)/(ForeignID) - remove the relationship between two database records, but don't actually delete the foreign object (NOT IMPLEMENTED YET) + - POST /api/v1/(ClassName)/(ID)/(MethodName) - executes a method on the given object (e.g, publish) + +## Searching + +You can trigger searches based on the fields specified on `DataObject::searchable_fields` and passed +through `DataObject::getDefaultSearchContext()`. Just add a key-value pair with the search-term +to the url, e.g. /api/v1/(ClassName)/?Title=mytitle. + +## Other url-modifiers + +- `&limit=`: Limit the result set +- `&relationdepth=`: Displays links to existing has-one and has-many relationships to a certain depth (Default: 1) +- `&fields=`: Comma-separated list of fields on the output object (defaults to all database-columns). + Handy to limit output for bandwidth and performance reasons. +- `&sort=&dir=` +- `&add_fields=`: Comma-separated list of additional fields, for example dynamic getters. + +## Access control + +Access control is implemented through the usual Member system with Basicauth authentication only. +By default, you have to bear the ADMIN permission to retrieve or send any data. +You should override the following built-in methods to customize permission control on a +class- and object-level: + +- `DataObject::canView()` +- `DataObject::canEdit()` +- `DataObject::canDelete()` +- `DataObject::canCreate()` + +See `DataObject` documentation for further details. + +You can specify the character-encoding for any input on the HTTP Content-Type. +At the moment, only UTF-8 is supported. All output is made in UTF-8 regardless of Accept headers.