Add list query example

Rename type IdentityState to Identity

rfc/0003 RFC GraphQL API for Duniter Client.md

@@ -52,7 +52,7 @@ The various implementation, for example the javascript one, are under the MIT li
 
 https://code.facebook.com/posts/121714468491809/relicensing-the-graphql-specification/
 
-## Librairies
+## Server Librairies
 
 GraphQl use queries that need to be parsed by the server implementation. So the use of a library avoid to write ourselves the base code.
 
@@ -68,6 +68,10 @@ Rust library is available [here](https://github.com/graphql-rust/juniper)
 
 http://graphql.org/code/#server-libraries
 
+## Client Libraries
+
+http://graphql.org/code/#graphql-clients
+
 ## GraphQL Verification API
 
 This is the name proposed for this API implementation.
@@ -113,9 +117,14 @@ They can be used on data in the blockchain or in the pool, as below :
 
 ## Types
 
-We explore here each type of document to request.
+We can request different types:
 
-### Identity
+- Data: a GraphQL json representation of the type of state requested from a document or an agregation of documents.
+- Raw: a GraphQL json containing a raw document.
+- Merckle Tree: a GraphQL json containing the root of the merckle tree from a state.
+- Lists: a list of state or others types enumerated above. Lists are limited to a maximum number by default and must be paginated.
+
+### Identity example
 
 #### Identities data
 
@@ -141,19 +150,19 @@ The data we need when we request Identity informations are :
 
 **GraphQL Request:**
 
-Parameters are mandatory, this is the key to retrieve the Indentity.
+Parameters are mandatory, this is the key to retrieve the Identity.
 Fields are optional like in any GrahQL query.
 
 ```javascript
-    {
+    query getIdentity {
       Identity(uid: "john", pubkey: "z7rDt7...", blockstamp: "22765-1AD84...") {
         member
         signature
         written
         outdistanced
         sentry
-        MembershipState
-        RevokeState
+        Membership
+        Revoke
       }
     }
 ```
@@ -168,12 +177,12 @@ Fields are optional like in any GrahQL query.
         "written": True
         "outdistanced": False,
         "sentry": True,
-        "MembershipState": {
+        "Membership": {
             "type": "IN",
             "blockstamp": "22965-7FD42...",
             "timestamp": "229658678",
         },
-        "RevokeState": {
+        "Revoke": {
             "revoked": True,
             "blockstamp": "22965-7FD42...",
             "timestamp": "229658678",
@@ -185,7 +194,7 @@ Fields are optional like in any GrahQL query.
 To get the full raw document type:
 
 ```javascript
-{
+query getIdentityRaw {
     IdentityRaw(uid: "john", pubkey: "z7rDt7...", blockstamp: "22765-1AD84...")
 }
 ```
@@ -234,7 +243,7 @@ merckle check is done on raw document fields.
 Send the verification request:
 
 ```javascript
-{
+query getIdentityMerckleTree {
     IdentityMerckleTree(uid: "john", pubkey: "z7rDt7...", blockstamp: "22765-1AD84...")
 }
 ```
@@ -249,6 +258,38 @@ Return the root of the merckle tree:
 }
 ```
 
-## The GraphQL server code
+**Query a list of identities UID:**
+
+For all list queries, an offset and a limit variable are specified by default.
+You can use these to paginate your list and avoid a "timebomb" request.
+
+*A "timebomb" request is a request on an infinitly growing list of entities,
+leading to slower and bigger responses that can, at the end, crash the server.*
+
+```javascript
+query getIdentities($offset: Int = 0, $limit: Int = 1000) {
+    Identities {
+        uid
+    }
+}
+```
+
+List response:
+
+```javascript
+{
+    "data": {
+        "Identities": [
+            {
+                "uid": "Alice"
+            },
+            {
+                "uid": "Bob"
+            }
+        ]
+}
+```
+
+**Send an Identity Document:**
 
-To do
+TODO