Added 'client doc' for notice.api:3.0

notice/api/3.0.md

@@ -6,7 +6,7 @@ requires:
   - error: 2.0
 ```
 
-Plan
+For developers
 ====
 
 [**I.** Overview](#i-overview)
@@ -56,6 +56,19 @@ Plan
 - [**1** API accessible documentation](#1---api-accessible-documentation)
 
 
+For clients
+====
+
+[**I.** Simple request](#i-simple-request)
+
+- [**1** URL](#1---URL)
+- [**2** variables](#2---variables)
+
+[**II.** Usage](#ii-usage)
+
+
+
+
 # **I.** Overview
 ## **1** Introduction & features
 
@@ -425,4 +438,104 @@ With the *all-in-config* method, we can generate a consistent documentation or o
 
 ## **1** - API accessible documentation
 
-You can request the API for information about the current URI by using the `OPTIONS` HTTP method.
+You can request the API for information about the current URI by using the `OPTIONS` HTTP method.
+
+
+====
+
+
+# **I.** Simple request
+## **1** - URL
+
+### format
+The `uri` format is as defined: `{base}/{path}/{GET_parameters}`, where
+- `{base}` is the server's *API* base uri (ex: `https://example.com/api/v1` or `https://api.exampl.com`)
+- `{path}` is the effective path you want to access (ex: `article/author`)
+- `{GET_parameters}` is a set of slash-separated values (ex: `val0/val1/val2//val4`)
+
+*Note:* GET parameters are not used as usual (`?var1=val1&var2=val2...`), instead the position in the URL gives them an implicit name which is `URL#`, where `#` is the index in the uri (beginning with 0).
+
+### example 1
+
+If you want to edit an article with the server's REST API, it could be defined as following:
+
+```yaml
+http: PUT
+path: article/{id_article}
+input:
+  body: new content of the article
+output:
+  updated: the updated article data
+```
+
+Let's take the example where you want to update the article which id is **23** and set its body to "**blabla new content**"
+
+`HTTP REQUEST`
+```
+PUT article/23 HTTP/1.0
+
+body=blabla+new+content
+```
+
+
+`HTTP RESPONSE`
+```
+HTTP/1.0 200 OK
+Content-Type: application/json
+
+{
+	"error": 0,
+	"ErrorDescription": "all right",
+
+	"updated": {
+		"id_article": 23,
+		"title": "article 23",
+		"body":  "blabla new content"
+	}
+
+}
+```
+
+### example 2
+
+If you want to get a specific article line, the request could be defined as following
+
+```yaml
+http: GET
+path: article/line/{id_article}/{no_line}
+input: -
+output:
+  articles: the list of matching lines
+```
+
+Let's take the example where you want to get **all articles** because `id_article` is set to optional, but you only want the first line of each so you have to give only the second parameter set to `1` (first line).
+
+*Solution:* The position in the `uri` where `id_article` must be, have to be left empty: it will result of 2 slashes (`//`).
+
+`HTTP REQUEST`
+```
+GET article/line//1 HTTP/1.0
+```
+
+
+`HTTP RESPONSE`
+```
+HTTP/1.0 200 OK
+Content-Type: application/json
+
+{
+	"error": 0,
+	"ErrorDescription": "all right",
+
+	"articles": [
+		{
+			"id_article": 23,
+			"line": [ 0: "blabla new content"
+		},{
+			"id_article": 25,
+			"line": [ 0: "some article"
+		}
+	]
+
+}
+```