wip

docs/api_docs/general_model.rst

@@ -83,20 +83,7 @@ Every service has a custom URL format as especified for each services.
 Representations
 ---------------
 
-Data formats that will support the platform are: **JSON** (initial
-version) and **XML** (in a future releases).
-
-The default format used by the platform is **JSON**.
-
-To specify a different format, you must add the parameter **“format”**
-in the request, as shown in the following example:
-
-::
-
-   http://<your_api_server.com>/service/<id_provider>?format=XML
-
-JSON format
-~~~~~~~~~~~
+Data formats that will supports the platform is currently only  **JSON**.
 
 Example data in JSON format:
 
@@ -106,18 +93,6 @@ Example data in JSON format:
        {"value":"12.3","timestamp":"17/09/2012T12:34:45"}
    ]}
 
-XML format
-~~~~~~~~~~
-
-Example data in XML format:
-
-.. code:: xml
-
-   <observation>
-       <value>12.3</value>
-       <timestamp>17/09/2012T12:34:45</timestamp>
-   </observation>
-
 Operators
 ---------
 
@@ -159,6 +134,9 @@ response **HTTP status codes.**
 | 403                   | Forbidden             | Not authorized for    |
 |                       |                       | the requested action  |
 +-----------------------+-----------------------+-----------------------+
+| 404                   | Not Found             | The requested entity  |
+|                       |                       | does not exist        |
++-----------------------+-----------------------+-----------------------+
 | 429                   | Too Many Requests     | Global quota or       |
 |                       |                       | entity quota exceed   |
 +-----------------------+-----------------------+-----------------------+

docs/api_docs/rate_limiting.rst

@@ -3,17 +3,17 @@ Rate Limiting
 
 Since v1.9, Sentilo offers rate limiting features for the REST API.
 
-Rest limiting prevents the Sentilo instance from request flooding and also protects
-subscribed external systems by limiting outbound requests.
+Rate limiting prevents the Sentilo instance from request flooding. Also, protects
+ external systems that are subscribed to Sentilo by limiting outcoming requests.
 
 Setting global limits
 ---------------------
 
-You can set global incoming quota `api.global_rate_limit.quota` in file
-sentilo-platform/sentilo-platform-server/src/main/resources/properties/config.properties.
-If left unset or set to 0, Sentilo won't apply no global limit.
+You can set global incoming quota :literal:`api.global_rate_limit.quota` in file
+:literal:`sentilo-platform/sentilo-platform-server/src/main/resources/properties/config.properties`.
+If left unset or set to 0, Sentilo won't apply any global limit.
 
-Also, global body length can be set using `api.body.max_length` variable.
+The maximum body length can also be set globally with :literal:`api.body.max_length` property.
 
 ::
 
@@ -84,7 +84,7 @@ subscription endpoint will contain following headers:
 |                                      | entity will be reset. Otherwise is 0.               |
 +--------------------------------------+-----------------------------------------------------+
 
-For example, consider the following case:
+For example, consider that the subscribed system receives a message, together with these headers:
 
 -  X-RateLimit-Outbound-Limit: 5
 -  X-RateLimit-Outbound-Remaining: 1
@@ -99,4 +99,4 @@ the two is met.
 
 
 
-.. |rl_entity_190.png| image:: _static/images/api_docs/rl_entity_190.png
+.. |rl_entity_190.png| image:: /_static/images/api_docs/rl_entity_190.png

docs/setup.rst

@@ -237,15 +237,24 @@ command from the directory where the file is located:
    recommend to change them before installing Sentilo in a production
    environment.
 
-If you change default values in the *init_data.js* and load them to
-MongoDB, you will have to modify the following properties before compiling
-and building Sentilo,
+If you change default values in the /sentilo/scripts/mongodb/init_data.js file and load them to
+MongoDB, you will have to modify the following properties before compiling and building Sentilo. So, following
+JS code from *init_data.js* :
+
+.. code:: javascript
+   db.application.insert({ "_id" : "sentilo-catalog", "_class" : "org.sentilo.web.catalog.domain.Application", "name" : "sentilo-catalog", "token" : "c956c302086a042dd0426b4e62652273e05a6ce74d0b77f8b5602e0811025066", "description" : "Catalog application", "email" : "sentilo@sentilo.org", "createdAt" : new ISODate(), "authorizedProviders" : [ ] });
+   db.user.insert({ "_id" : "platform_user", "_class" : "org.sentilo.web.catalog.domain.User", "password" : "sentilo", "name" : "Platform user", "description" : "PubSub platform user. Do not remove  it!.", "email" : "sentilo@sentilo.org", "createdAt" : new ISODate(), "active" : true, "roles" : [ "PLATFORM" ] });
+
+Corresponds with:
 
 .. code:: properties
 
    rest.client.identity.key=c956c302086a042dd0426b4e62652273e05a6ce74d0b77f8b5602e0811025066
    catalog.rest.credentials=platform_user:sentilo
 
+, being *rest.client.identity.key* the token of a *sentilo-catalog* application, and *catalog.rest.credentials* value
+is a combination of user *platform_user* and it's password.
+
 These properties are in following files:
 
 ::
@@ -267,8 +276,7 @@ These data is defined in the file:
 
    ./scripts/mongodb/init_test_data.js
 
-and, as pointed aout above, you should run the following command to load
-it:
+and, as pointed above, you should run the following command to load it:
 
 ::
 
@@ -350,8 +358,8 @@ code:
    -Duser.timezone=UTC
 
 
-Subscription/publication platform settings
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+API server (Subscription/publication) settings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Sentilo default settings consider subscription/publication server
 (a.k.a. *PubSub* server) will be listening on 127.0.0.1:8081
@@ -410,10 +418,10 @@ You will find the WAR artifact at the following subdirectory:
 
    ./sentilo-catalog-web/target/sentilo-catalog-web.war
 
-Installing subscription/publication server
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Installing API server (subscription/publication)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-After build Sentilo, to install the PubSub server, you need to follow
+After build Sentilo, to install the API (pub/sub) server, you need to follow
 the following steps:
 
 a. Into the directory
@@ -558,35 +566,29 @@ You will find more information about this feature in the
 Enable anonymous access to REST API
 -----------------------------------
 
-By default, anonymous access to REST API is disabled which means that
+By default, anonymous access to REST API is disabled, e.g.
 all requests to REST API must be identified with the
 `identity_key <./api_docs/security.html>`__ header.
 
-From version 1.5, we provide a new feature that allows anonymous access
-to REST API but only for read *authorized* data of your Sentilo instance
-(here *authorized* means that you should configure your Catalog to
-define which data could be accessed anonymously from REST requests).
+Enabling anonymous access to the REST API means that only
+*authorized* data of your Sentilo instance can be accessed.
+Access to authorized data is described below.
+
+In order to enable anonymous access you should modify the file
+sentilo-platform/sentilo-platform-server/src/main/resources/properties/config.properties:
 
-In order to enable anonymous access you should modify the following
-properties:
 
 .. code:: properties
 
    # Properties to configure the anonymous access to Sentilo
    enableAnonymousAccess=false
    anonymousAppClientId=
 
-configured in the following file:
-
-::
-
-   sentilo-platform/sentilo-platform-server/src/main/resources/properties/config.properties
 
-This configuration has not mystery: if anonymous access is enabled
-(*enableAnonymousAccess=true*) then all anonymous requests to REST API
-are internally considered as is they have been performed by the
-application client identified by the *anonymousAppClientId* property
-value (this application client should exists into your Sentilo Catalog),
+If anonymous access is enabled (*enableAnonymousAccess=true*),
+then all anonymous requests to REST API are internally considered as is they have
+been performed by the application client identified by the *anonymousAppClientId* property
+value (this application client should exist into your Sentilo Catalog),
 and therefore these requests will have the same data restrictions as the
 requests performed by this client application.