Refactor api

docs/_config.yml

@@ -22,7 +22,7 @@ permalink: pretty
 exclude: ["vendor/bundle", "node_modules/", "*.gemspec", "*.gem", "Gemfile", "Gemfile.lock", "package.json", "package-lock.json",  "script/", "LICENSE.txt", "lib/", "bin/", "README.md", "Rakefile"]
 
 # Set a path/url to a logo that will be displayed instead of the title
-#logo: "/assets/images/just-the-docs.png"
+logo: "/assets/img/nuvladocs-logo.png"
 
 # Enable or disable the site search
 # Supports true (default) or false

docs/_includes/api/group-response.md

@@ -0,0 +1,7 @@
+```json
+{
+  "status" : 201,
+  "message" : "group/dev created",
+  "resource-id" : "group/dev"
+}
+```

docs/_includes/api/group.sh

@@ -0,0 +1,10 @@
+curl -XPOST https://nuvla.io/api/group -H 'content-type:application/json' -b cookies -d '''
+    {
+      "template": {
+        "href": "group-template/generic",
+        "group-identifier": "dev",
+        "name": "Dev",
+        "description": "Development group"
+      }
+    }
+'''

docs/_includes/api/invite-response.md

@@ -0,0 +1,7 @@
+```json
+{
+  "status" : 200,
+  "message" : "successfully invited to group/dev",
+  "resource-id" : "group/dev"
+}
+```

docs/_includes/api/invite.sh

@@ -0,0 +1,3 @@
+curl -XPOST https://nuvla.io/api/group/dev/invite -H 'content-type:application/json' -b cookies -d '''
+    {"username": "foobar@example.com"}
+'''

docs/_includes/api/login_apikey.sh → docs/_includes/api/login-apikey.sh

@@ -1,4 +1,4 @@
-curl -XPOST https://nuvla.io/api/session -H 'content-type:application/json' -b cookies -d '''
+curl -XPOST https://nuvla.io/api/session -H 'content-type:application/json' -c cookies -d '''
     {
       "template": {
         "href": "session-template/api-key",

docs/_includes/api/logout-response.md

@@ -0,0 +1,7 @@
+```json
+{
+  "status" : 200,
+  "message" : "session/689df57a-b217-43eb-bf94-85a0ab638e2c deleted",
+  "resource-id" : "session/689df57a-b217-43eb-bf94-85a0ab638e2c"
+}
+```

docs/_includes/api/session-get-peers-response.md

@@ -0,0 +1,7 @@
+```json
+{
+  "user/41d08575-77c2-45fb-9174-9b34bca81dc5" : "titi@other.example.com",
+  "user/55366c0f-d1d4-4c15-bf04-4dfb35c23ea2" : "tata@exmaple.com",
+  "user/d5c54236-94a3-49be-8013-128ead0b5836" : "toto@example.com
+}
+```

docs/_includes/api/session-switch-group-response.md

@@ -0,0 +1,32 @@
+```json
+{
+  "active-claim" : "user/d5c54236-94a3-49be-8013-128ead0b5836",
+  "client-ip" : "172.17.0.1",
+  "expiry" : "2021-12-29T12:44:55.000Z",
+  "method" : "password",
+  "updated" : "2021-12-22T12:44:55.150Z",
+  "roles" : "group/nuvla-anon group/nuvla-user session/51179a6b-f9e2-4ae9-af16-a0955baf78c8 user/d5c54236-94a3-49be-8013-128ead0b5836",
+  "created" : "2021-12-20T13:52:08.789Z",
+  "template" : {
+    "href" : "session-template/password"
+  },
+  "updated-by" : "user/d5c54236-94a3-49be-8013-128ead0b5836",
+  "created-by" : "group/nuvla-anon",
+  "id" : "session/51179a6b-f9e2-4ae9-af16-a0955baf78c8",
+  "resource-type" : "session",
+  "identifier" : "toto@example.com",
+  "acl" : {
+    "edit-data" : [ "group/nuvla-admin" ],
+    "owners" : [ "session/51179a6b-f9e2-4ae9-af16-a0955baf78c8" ],
+    "view-acl" : [ "group/nuvla-admin" ],
+    "delete" : [ "group/nuvla-admin" ],
+    "view-meta" : [ "group/nuvla-admin" ],
+    "edit-acl" : [ "group/nuvla-admin" ],
+    "view-data" : [ "group/nuvla-admin" ],
+    "manage" : [ "group/nuvla-admin" ],
+    "edit-meta" : [ "group/nuvla-admin" ]
+  },
+  "groups" : "group/eo",
+  "user" : "user/d5c54236-94a3-49be-8013-128ead0b5836"
+}
+```

docs/_includes/api/sessions-response.md

@@ -0,0 +1,53 @@
+```json
+{
+  "count" : 1,
+  "acl" : {
+    "query" : [ "group/nuvla-anon" ],
+    "add" : [ "group/nuvla-anon" ]
+  },
+  "resource-type" : "session-collection",
+  "id" : "session",
+  "resources" : [ {
+    "client-ip" : "172.17.0.1",
+    "expiry" : "2021-12-29T12:57:54.000Z",
+    "method" : "password",
+    "updated" : "2021-12-22T12:57:55.002Z",
+    "roles" : "group/nuvla-anon group/nuvla-user user/d5c54236-94a3-49be-8013-128ead0b5836 session/8ed0f0cc-ea54-4e07-9e11-4ba68bb7113b",
+    "created" : "2021-12-22T12:57:55.002Z",
+    "template" : {
+      "href" : "session-template/password"
+    },
+    "created-by" : "group/nuvla-anon",
+    "id" : "session/8ed0f0cc-ea54-4e07-9e11-4ba68bb7113b",
+    "resource-type" : "session",
+    "identifier" : "toto@example.com",
+    "acl" : {
+      "edit-data" : [ "group/nuvla-admin" ],
+      "owners" : [ "session/8ed0f0cc-ea54-4e07-9e11-4ba68bb7113b" ],
+      "view-acl" : [ "group/nuvla-admin" ],
+      "delete" : [ "group/nuvla-admin" ],
+      "view-meta" : [ "group/nuvla-admin" ],
+      "edit-acl" : [ "group/nuvla-admin" ],
+      "view-data" : [ "group/nuvla-admin" ],
+      "manage" : [ "group/nuvla-admin" ],
+      "edit-meta" : [ "group/nuvla-admin" ]
+    },
+    "operations" : [ {
+      "rel" : "delete",
+      "href" : "session/8ed0f0cc-ea54-4e07-9e11-4ba68bb7113b"
+    }, {
+      "rel" : "get-peers",
+      "href" : "session/8ed0f0cc-ea54-4e07-9e11-4ba68bb7113b/get-peers"
+    }, {
+      "rel" : "switch-group",
+      "href" : "session/8ed0f0cc-ea54-4e07-9e11-4ba68bb7113b/switch-group"
+    } ],
+    "groups" : "group/eo",
+    "user" : "user/d5c54236-94a3-49be-8013-128ead0b5836"
+  } ],
+  "operations" : [ {
+    "rel" : "add",
+    "href" : "session"
+  } ]
+}
+```

docs/_includes/api/switch-group.sh

@@ -0,0 +1,3 @@
+curl -XPOST https://nuvla.io/api/session/51179a6b-f9e2-4ae9-af16-a0955baf78c8/switch-group -H 'content-type:application/json' -b cookies -c cookies -d '''
+    {"claim": "group/x"}
+'''

docs/_includes/old_nuvlabox_warning.html

@@ -1 +1 @@
-<div class="warning mb-5">Warning: this is not the documentation of the latest version of the NuvlaBox. Go <a href="/nuvlabox/v2">here</a> to access the latest version.</div>
+<div class="warning mb-5">Warning: this is not the documentation of the latest version of the NuvlaBox. Go <a href="/nuvlabox/nuvlabox-engine/v2">here</a> to access the latest version.</div>

docs/nuvla/advanced-usage/api/cloud-entry-point.md

@@ -0,0 +1,29 @@
+---
+layout: page
+title: Cloud Entry Point
+nav_order: 2
+parent: API
+has_children: false
+---
+
+
+# Cloud Entry Point
+
+{% include request_snippet.md file='api/credential-amazonec2.sh' actions='GET' endpoint='/api/cloud-entry-point' maincolor='none' prefix='allowed:' lettercolor='black' %}
+
+The primary directory of resources is the Cloud Entry Point (CEP), which contains a list of named resource collections and their URLs (in the href field) relative to the baseURI value. The CEP also contains some other metadata.
+
+The endpoint is accessible for all registered and anonymous Nuvla users.
+
+---
+
+_Examples_
+
+## Get the cloud entry point
+
+{% include request_snippet.md file='api/cep.sh' actions='GET' endpoint='/api/cloud-entry-point' %}
+
+{% include code_snippet.md file='api/cep.sh' language='shell' %}
+
+{% include response_snippet.md file='api/cep-response.md' %}
+

docs/nuvla/advanced-usage/api/common-design.md

@@ -0,0 +1,197 @@
+---
+layout: page
+title: Common Design
+nav_order: 1
+parent: API
+has_children: true
+---
+
+# Common Design
+
+
+| Action        | HTTP Method | Target              |
+| --- | --- | --- |
+| Search        | GET or PUT  | resource collection |
+| Add (create)  | POST        | resource collection |
+| Bulk_delete   | DELETE      | resource collection |
+| Bulk_action   | PATCH       | resource collection |
+| Read          | GET         | resource            |
+| Edit (update) | PUT         | resource            |
+| Delete        | DELETE      | resource            |
+
+The Nuvla REST API endpoints are constructed with the following pattern:
+
+`/api/<resource-name>/<resource-uuid>/<action>/`
+
+where
+
+ - `<resource-name>` is the Kebab Case name of the resource collection you're accessing,
+ - `<resource-uuid>` is the unique identifier for the specific resource you're managing,
+ - `<action>` is a custom additional operation that might be allowed for that resource.
+
+On top of that, Nuvla's REST API also offers searching and querying through a parameter-based set of keywords:
+
+`/api/<resource-name>?param=value&param=value...`
+
+where
+
+|  Parameter  |  Description |  Examples |
+| --- | --- | --- |
+| `filter` | Used to return only the set of resources that have an `attribute` matching a certain `value` | `?filter=name="my-resource"` <br><br> `?filter=people/gender!="male" and people/age>=21` <br><br> `?filter=application-name^="my-app-"` |
+| `orderby` | To order the returned resources by the specified attribute | `?orderby=created:desc` <br><br> `?orderby=people/surname:asc` |
+| `aggregation` | On top of the requested resources, it will also return on-the-fly aggregations based on the specified function. Available functions: `avg`, `max`, `min`, `sum`, `cardinality`, `terms`, `stats`, `extendedstats`, `percentiles`, `value_count`, `missing`  | `?aggregation=avg:people/age` | 
+| `last` and `first` | Returns a range of resources by setting the first and last (1-based) query parameters | `?first=10&last=20` |
+| `select` | Selects only certain attributes to be returned by the server. Avoiding sending information that will not be useful reduces the load on the network and the server | `?select=people/id` |
+
+Nuvla's API also provide custom operations for certain resources. These will be covered individually in the subsections below.
+
+Here are a few examples on how to construct the different HTTP requests:
+
+ - **GET** all the resources of a specific type:
+
+    `GET /api/<resource-name>`
+
+ - **GET** a specific resource:
+
+    `GET /api/<resource-name>/<resource-uuid>`
+
+ - **CREATE** a new resource:
+
+    ```
+  POST     /api/<resource-name>
+  HEADERS  content-type:application/json
+  DATA     <JSON resource>
+    ```
+
+ - **EDIT** an existing resource:
+
+    ```
+  PUT      /api/<resource-name>/<resource-uuid>
+  HEADERS  content-type:application/json
+  DATA     <JSON with the attribute name and value to be changed>
+    ```
+
+    In case you want to delete existing attributes , add the attributes names in `select` parameter
+    and do not send these attributes in `DATA` request body.
+
+ - **DELETE** a resource:
+
+    `DELETE /api/<resource-name>/<resource-uuid>`
+
+ - **QUERY** on resources:
+
+    `GET /api/<resource-name>?param=value&param=value`
+
+    *or*
+
+    ```
+  PUT      /api/<resource-name>
+  HEADERS  content-type:application/x-www-form-urlencoded
+  DATA     <Form data with parameters (e.g. filter,last)>
+    ```
+
+ - **BULK_DELETE** of resources:
+
+    `DELETE /api/<resource-name>?param=value&param=value`
+
+   *or*
+
+    ```
+  DELETE   /api/<resource-name>
+  HEADERS  content-type:application/x-www-form-urlencoded, bulk:true
+  DATA     <Form data with parameters (e.g. filter,last)>
+    ```
+
+
+ - **BULK_ACTION** of resources:
+
+    `PATCH /api/<resource-name>/<action>?param=value&param=value`
+
+   *or*
+
+    ```
+  PATCH    /api/<resource-name>
+  HEADERS  content-type:application/x-www-form-urlencoded, bulk:true
+  DATA     <Form data with parameters (e.g. filter,last)>
+    ```
+
+
+## Resources
+
+All the Nuvla API calls to retrieve resources will return a JSON output, and you'll notice that all of these outputs contain a set of common attributes:
+
+ - _**id**_: unique resource identifier, defined by the API server
+ - _**acl**_: fine-grained access-control list, used for managing authorization process for each resource and its collections of resources. If not defined by the user, the API server will default it based on the requesting user credentials.
+ - _**created**_: timestamp of creation, defined by the API server
+ - _**created-by**_: user id who created the resource (useful to trace user action when he has switched to a group)
+ - _**updated**_: timestamp of the last update, defined by the API server
+ - _**updated-by**_: user id who updated the resource (useful to trace user action when he has switched to a group)
+ - _**resource-type**_: type of resource, defined by the API server
+ - _**parent**_: reference to parent resource
+ - _**operations**_: set of available operations for that resource, defined by the API server
+ - _**name**_: optional user-friendly name for a specific resource, defined by the user or defaulted to `None` if undefined
+ - _**description**_: optional verbose description for a specific resource, defined by the user or defaulted to `None` if undefined      
+
+Resources are managed individually, which means that the data schemas and available operations might defer from one to the other. These options are all explained and exemplified in the following sections.
+
+
+
+## Filter syntax
+
+Filter parameter is used to search, to run bulk delete and to run bulk operations on existing resources.
+
+It could be a simple query e.g.
+
+- `name='hello'`
+
+- `acl/delete = 'group/demo'`
+
+- `created<'2021-11-24T19:59:18Z'`
+
+- `version < 2`
+
+- `location intersects 'POINT(13.86 60.84)'`
+
+- `online!=true`
+
+- `description=null`
+
+- `tags='eo'`
+
+- `fulltext == 'Demo*'`
+
+or a complex one with parenthesis and combination of logical [`or`, `and`] expression.
+
+- `(created<'2021-11-24T19:59:18Z' or name^='hello') and location intersects 'POINT(13.86 60.84)'` 
+
+### Supported Values in filter
+
+| Name | Description | Example |
+|---|---|
+| Text | Single or double quoted text | `"foobar"` `'foobar'` |
+| Date | Single or double quoted UTC timestamp or `now` expression | `'2021-11-24T19:59:18Z'` `'now<30m'` `'now>30d'` |
+| Numeric | Integer or Float numbers | `3.14159` `3`|
+| Boolean |  | `true` `false` |
+| Geo-point | Single or double quoted [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) string | `'POLYGON((-49.2 19.6,65.7 19.6,65.7 67.4,-49.2 67.4,-49.2 19.6))'` |
+| Geo-shape | Single or double quoted [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)  string | `'POLYGON((-49.2 19.6,65.7 19.6,65.7 67.4,-49.2 67.4,-49.2 19.6))'` |
+| Null |  | `null` |
+
+Arrays are a special case and searches are executed on their content as if they was a simple value.
+E.g. tags field is defined as an array of string. In case we would like to search if tags contains "eo", the filter would be `tags='eo'`.
+
+### Operations
+
+| Name | Symbol | Supported values | Details |
+|---|---|---|---|
+| Equal | = | Numeric, Date, Text, Boolean, null |  |
+| Not Equal | != | Numeric, Date, Text, Boolean, null |  |
+| Less than | < | Numeric, Date, Text |  |
+| Less than or Equal | <= | Numeric, Date, Text |  |
+| Greater than | > | Numeric, Date, Text |  |
+| Greater than or Equal | >= | Numeric, Date, Text |  |
+| Start with | ^= | Text |  |
+| Full-text search | == | Text | Works only on field  `name` ,  `description`  or  `fulltext`  which is a virtual field that regroup more or less the full resource words. |
+| Intersects | intersects | Geo-Point, Geo-shape | Return all documents whose geo_shape or geo_point field intersects the query geometry. |
+| Disjoint | disjoint | Geo-shape | Return all documents whose geo_shape or geo_point field has nothing in common with the query geometry. |
+| Within | within | Geo-shape | Return all documents whose geo_shape or geo_point field is within the query geometry. Line geometries are not supported. |
+| Contains | contains | Geo-shape | Return all documents whose geo_shape or geo_point field contains the query geometry. |