Documentation

README.md

 # Restful Storm
 
-This application aim to provide restful access to [[Storm http://git.afi-sa.fr/afi/storm]] enabled models.
\ No newline at end of file
+This application aim to provide restful access to [Storm](http://git.afi-sa.fr/afi/storm) enabled models.
+
+## Installation
+
+### Requirements
+
+You need Apache with rewrite module, PHP 5.4+ and MySQL 5+.
+
+Obviously you also need [Storm](http://git.afi-sa.fr/afi/storm).
+
+This application defines a git submodule for Storm which itself defines a submodule for a customized Zend Framework 1.6. Please see git documentation te learn more about submodules.
+> tip : `/build.sh` contains commands to init and update them recursively
+
+### Storm models
+
+Creating Storm models for your datas is trivial.
+```
+class My_Model extends Storm_Model_Abstract {
+      protected $_table_name = 'my_table_name';
+      protected $_table_primary = 'id_table_name'; // needed only if PK is not named 'id'
+}
+```
+From here you can use Storm super powers to access and manipulate your datas.
+
+See [Storm documentation](http://git.afi-sa.fr/afi/storm/blob/master/README.md) to learn more.
+
+### Configuration
+
+Copy `/config.php.dist` to `/config.php` and edit it.
+
+`sgbd` section should be self explanatory
+
+`modelspath` should contain base path to your Storm enabled models.
+
+They should follow Zend Framework 1.x class loader naming convention : **My_Storm_Model** should reside in **My/Storm/Model.php** file.
+
+`models` contains access and capabilities configuration array.
+* key contains model's name
+* value is an array
+  * caps contains capabilities name separated by ';' between index, show, create, update, delete
+  * fields contains fields name separated by ';', those fields will be included in JSON responses, 'id' field is always included
+
+```
+'models' => [
+	 Class_Album' => [
+		'caps' => 'index;show',
+		'fields' => 'titre']]
+```
+
+'*' can be used as an "allow all" wildcard.
+* as a model name allow access to all your models
+* as a caps value allow all capabilities
+* as a fields value allow display of all fields in JSON response
+
+Then you can define a read all access as
+```
+'models' => [
+	 '*' => [
+		'caps' => 'index;show',
+		'fields' => '*']]
+```
+
+And you can combine default access with specifics.
+```
+'models' => [
+	 '*' => [ // any models
+		'caps' => 'index;show', // is searchable and showable
+		'fields' => ''], // but only show its id, no other fields
+
+	'Class_Album' => [ // this model
+		'caps' => '*', // is fully handled in this app
+		'fields' => '*', // and show all its fields
+	]]
+```
+
+
+## Usage
+
+### Catalog
+
+Accessing `/catalog` URL will show a page reflecting your configuration.
+
+For each model it will display 
+* allowed methods and their URLs
+* displayed fields
+
+### Index
+
+**URL** : /[model name]/
+```
+http://localhost/Restful/Class_Batch
+```
+
+**Output** : JSON array containing matching models JSON representations.
+```
+[{"type":"MOISSONNAGE_ARTEVOD","last_run":"2014-07-30 22:02:05","id":3}]
+```
+Responses are limited to 100 results, to get next results you should specify a page number.
+
+**URL** : /[model name]/page/[page number]
+```
+http://localhost/Restful/Class_Notice/page/45
+```
+When a response returns an empty array their are no more results.
+
+You can specify order clause
+
+**URL** : /[model name]/order/[order clause]
+```
+http://localhost/Restful/Class_Notice/order/id%20desc
+```
+
+You can find models matching exact properties values
+
+**URL** : /[model name]/[property name]/[exact value]
+```
+http://localhost/Restful/Class_Album/titre/La%20tulipe%20noire
+```
+or
+```
+http://localhost/Restful/Class_Album/titre/La%20tulipe%20noire/genre/roman
+```
+
+You can even specify an SQL where clause
+
+**URL** : /[model name]/[property name]/[exact value]
+```
+http://localhost/Restful/Class_Album/where/titre%20like%20'La%25'
+```
+But you have to choose between simple property exact value matching or where clause.
+
+Full featured query
+```
+http://localhost/Restful/Class_Album/where/titre%20like%20'La%25'/order/id%20desc/page/2
+```
+
+### Show
+
+When you already know the primary key of a model, you can access it directly with
+
+**URL** : /[model name]/[primary key value]
+```
+http://localhost/Restful/Class_Batch/3
+```
+
+**Output** : matching model JSON representation.
+```
+{"type":"MOISSONNAGE_ARTEVOD","last_run":"2014-07-30 22:02:05","id":3}
+```
+
+### Create, Update, Delete are not implemented yet