diff --git a/docs/_config.yml b/docs/_config.yml index e5f0f7d..c1034ad 100644 --- a/docs/_config.yml +++ b/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 diff --git a/docs/_includes/api/group-response.md b/docs/_includes/api/group-response.md new file mode 100644 index 0000000..006790d --- /dev/null +++ b/docs/_includes/api/group-response.md @@ -0,0 +1,7 @@ +```json +{ + "status" : 201, + "message" : "group/dev created", + "resource-id" : "group/dev" +} +``` \ No newline at end of file diff --git a/docs/_includes/api/group.sh b/docs/_includes/api/group.sh new file mode 100644 index 0000000..d4839fc --- /dev/null +++ b/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" + } + } +''' diff --git a/docs/_includes/api/invite-response.md b/docs/_includes/api/invite-response.md new file mode 100644 index 0000000..c7d149c --- /dev/null +++ b/docs/_includes/api/invite-response.md @@ -0,0 +1,7 @@ +```json +{ + "status" : 200, + "message" : "successfully invited to group/dev", + "resource-id" : "group/dev" +} +``` \ No newline at end of file diff --git a/docs/_includes/api/invite.sh b/docs/_includes/api/invite.sh new file mode 100644 index 0000000..4044921 --- /dev/null +++ b/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"} +''' diff --git a/docs/_includes/api/login_apikey.sh b/docs/_includes/api/login-apikey.sh similarity index 88% rename from docs/_includes/api/login_apikey.sh rename to docs/_includes/api/login-apikey.sh index 4e44317..2fa8981 100644 --- a/docs/_includes/api/login_apikey.sh +++ b/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", diff --git a/docs/_includes/api/logout-response.md b/docs/_includes/api/logout-response.md new file mode 100644 index 0000000..f38acf5 --- /dev/null +++ b/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" +} +``` \ No newline at end of file diff --git a/docs/_includes/api/session-get-peers-response.md b/docs/_includes/api/session-get-peers-response.md new file mode 100644 index 0000000..275ce21 --- /dev/null +++ b/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 +} +``` \ No newline at end of file diff --git a/docs/_includes/api/session-switch-group-response.md b/docs/_includes/api/session-switch-group-response.md new file mode 100644 index 0000000..d2ddc9e --- /dev/null +++ b/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" +} +``` \ No newline at end of file diff --git a/docs/_includes/api/sessions-response.md b/docs/_includes/api/sessions-response.md new file mode 100644 index 0000000..6a8dc60 --- /dev/null +++ b/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" + } ] +} +``` \ No newline at end of file diff --git a/docs/_includes/api/switch-group.sh b/docs/_includes/api/switch-group.sh new file mode 100644 index 0000000..4656ee0 --- /dev/null +++ b/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"} +''' diff --git a/docs/assets/img/nuvladocs-logo.png b/docs/assets/img/nuvladocs-logo.png new file mode 100644 index 0000000..633a58b Binary files /dev/null and b/docs/assets/img/nuvladocs-logo.png differ diff --git a/docs/nuvla/advanced-usage/api/cloud-entry-point.md b/docs/nuvla/advanced-usage/api/cloud-entry-point.md new file mode 100644 index 0000000..2aee167 --- /dev/null +++ b/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' %} + diff --git a/docs/nuvla/advanced-usage/api/common-design.md b/docs/nuvla/advanced-usage/api/common-design.md new file mode 100644 index 0000000..dc69baf --- /dev/null +++ b/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////` + +where + + - `` is the Kebab Case name of the resource collection you're accessing, + - `` is the unique identifier for the specific resource you're managing, + - `` 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/?param=value¶m=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"`

`?filter=people/gender!="male" and people/age>=21`

`?filter=application-name^="my-app-"` | +| `orderby` | To order the returned resources by the specified attribute | `?orderby=created:desc`

`?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/` + + - **GET** a specific resource: + + `GET /api//` + + - **CREATE** a new resource: + + ``` + POST /api/ + HEADERS content-type:application/json + DATA + ``` + + - **EDIT** an existing resource: + + ``` + PUT /api// + HEADERS content-type:application/json + DATA + ``` + + 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//` + + - **QUERY** on resources: + + `GET /api/?param=value¶m=value` + + *or* + + ``` + PUT /api/ + HEADERS content-type:application/x-www-form-urlencoded + DATA
+ ``` + + - **BULK_DELETE** of resources: + + `DELETE /api/?param=value¶m=value` + + *or* + + ``` + DELETE /api/ + HEADERS content-type:application/x-www-form-urlencoded, bulk:true + DATA + ``` + + + - **BULK_ACTION** of resources: + + `PATCH /api//?param=value¶m=value` + + *or* + + ``` + PATCH /api/ + HEADERS content-type:application/x-www-form-urlencoded, bulk:true + DATA + ``` + + +## 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. | diff --git a/docs/nuvla/advanced-usage/api/credential.md b/docs/nuvla/advanced-usage/api/credential.md new file mode 100644 index 0000000..57fc248 --- /dev/null +++ b/docs/nuvla/advanced-usage/api/credential.md @@ -0,0 +1,99 @@ +--- +layout: page +title: Credential +nav_order: 5 +parent: API +has_children: false +--- + +# credential + +{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET PUT DELETE' endpoint='/api/credential/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} + +The `credential` resource is used to save all the credentials necessary to +manage your Nuvla resources. From API keys, to Container Orchestration Engine +credentials, TLS certificates, etc. Most of the credentials are expected to be +provided by the user, some are generated by Nuvla (e.g. API key). + +--- +_Examples_ + +## Generate an API key credential + +{% include request_snippet.md file='api/credential-apikey.sh' actions='POST' endpoint='/api/credential' %} + +{% include code_snippet.md file='api/credential-apikey.sh' language='shell' %} + +{% include response_snippet.md file='api/credential-apikey-response.md' %} + + + +## Docker Swarm token credential + +{% include request_snippet.md file='api/credential-swarmtoken.sh' actions='POST' endpoint='/api/credential' %} + +{% include code_snippet.md file='api/credential-swarmtoken.sh' language='shell' %} + +{% include response_snippet.md file='api/credential-swarmtoken-response.md' %} + + + +## Infrastructure Service S3 credential + +{% include request_snippet.md file='api/credential-s3.sh' actions='POST' endpoint='/api/credential' %} + +{% include code_snippet.md file='api/credential-s3.sh' language='shell' %} + +{% include response_snippet.md file='api/credential-s3-response.md' %} + + +## Infrastructure Service Docker Swarm HTTP API credential + +{% include request_snippet.md file='api/credential-swarm.sh' actions='POST' endpoint='/api/credential' %} + +{% include code_snippet.md file='api/credential-swarm.sh' language='shell' %} + +{% include response_snippet.md file='api/credential-swarm-response.md' %} + + +## Infrastructure Service Kubernetes HTTP API credential + +{% include request_snippet.md file='api/credential-kubernetes.sh' actions='POST' endpoint='/api/credential' %} + +{% include code_snippet.md file='api/credential-kubernetes.sh' language='shell' %} + +{% include response_snippet.md file='api/credential-kubernetes-response.md' %} diff --git a/docs/nuvla/advanced-usage/api/deployment.md b/docs/nuvla/advanced-usage/api/deployment.md new file mode 100644 index 0000000..4fc713b --- /dev/null +++ b/docs/nuvla/advanced-usage/api/deployment.md @@ -0,0 +1,24 @@ +--- +layout: page +title: Deployment +nav_order: 6 +parent: API +has_children: false +--- + +# deployment + +{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET PUT DELETE' endpoint='/api/deployment/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} + +The `deployment` resource allows you to deploy an instance of a `module`. + +--- +_Examples_ + +## Start/Stop an application + +{% include request_snippet.md file='api/deployment.sh' actions='POST PUT GET' endpoint='/api/deployment' %} + +{% include code_snippet.md file='api/deployment.sh' language='shell' %} + +{% include response_snippet.md file='api/deployment-response.md' %} diff --git a/docs/nuvla/advanced-usage/api/group.md b/docs/nuvla/advanced-usage/api/group.md new file mode 100644 index 0000000..3067605 --- /dev/null +++ b/docs/nuvla/advanced-usage/api/group.md @@ -0,0 +1,52 @@ +--- +layout: page +title: Group +nav_order: 4 +parent: API +has_children: false +--- + + +# Group + +{% include request_snippet.md actions='POST GET DELETE' endpoint='/api/group/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} + +The `group` resource allows you to: + + - create new groups + - invite users to join a group + +Group is a resource that allow users to have a common account/view on Nuvla on created resources (see `session` switch-group operation) or shared ones (via ACL). + +## Attributes + +**NOTE:** only common attributes for this resource + +--- + +## Examples + +**NOTE:** for later usage, we store the authenticated session in a file called _cookies_ + +Group is a templated resource. To create/add a new group, you have to refer to a +group-template resource. + +{% include request_snippet.md actions='GET' endpoint='/api/group-template' %} + +## Create a group + +{% include request_snippet.md actions='POST' endpoint='/api/group' %} + +{% include code_snippet.md file='api/group.sh' language='shell' %} + +{% include response_snippet.md file='api/group-response.md' %} + +## Invite operation + +You can invite a user to join a group by email doing as follow. + +{% include request_snippet.md actions='POST' endpoint='/api/group/dev/invite' %} + +{% include code_snippet.md file='api/invite.sh' language='shell' %} + +{% include response_snippet.md file='api/invite-response.md' %} diff --git a/docs/nuvla/advanced-usage/api/index.md b/docs/nuvla/advanced-usage/api/index.md new file mode 100644 index 0000000..883b263 --- /dev/null +++ b/docs/nuvla/advanced-usage/api/index.md @@ -0,0 +1,14 @@ +--- +layout: page +title: API +parent: Advanced Usage +nav_order: 1 +has_children: true +--- + +# REST API + +Nuvla provides a uniform and extensible HTTP-based RESTful API, for the management of Nuvla resources. A Nuvla resource can be anything you can perform an action on, through Nuvla, like your own user profile, a Nuvla application, credentials, etc. + +Users have at their disposal all the usual CRUD (Create, Read, Update, Delete) operations, plus Searching, Querying, Bulk delete and Bulk actions. + diff --git a/docs/nuvla/advanced-usage/api/infrastructure-service-group.md b/docs/nuvla/advanced-usage/api/infrastructure-service-group.md new file mode 100644 index 0000000..b6b62f6 --- /dev/null +++ b/docs/nuvla/advanced-usage/api/infrastructure-service-group.md @@ -0,0 +1,28 @@ +--- +layout: page +title: Infrastructure Service Group +nav_order: 5 +parent: API +has_children: false +--- + +# infrastructure-service-group + +{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET DELETE' endpoint='/api/infrastructure-service-group/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} + +The `infrastructure-service-group` resource is a logical container for your infrastructure-service and respective credential and data resources. + + +--- +_Examples_ + + +## Create an infrastructure-service-group + +{% include request_snippet.md file='api/infrastructure-service-group.sh' actions='POST' endpoint='/api/infrastructure-service-group' %} + +{% include code_snippet.md file='api/infrastructure-service-group.sh' language='shell' %} + +{% include response_snippet.md file='api/infrastructure-service-group-response.md' %} + + diff --git a/docs/nuvla/advanced-usage/api/infrastructure-service.md b/docs/nuvla/advanced-usage/api/infrastructure-service.md new file mode 100644 index 0000000..a1aeba5 --- /dev/null +++ b/docs/nuvla/advanced-usage/api/infrastructure-service.md @@ -0,0 +1,74 @@ +--- +layout: page +title: Infrastructure Service +nav_order: 4 +parent: API +has_children: false +--- + +# infrastructure-service + +{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET PUT DELETE' endpoint='/api/infrastructure-service/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} + +The `infrastructure-service` resource represents any manageable service with a working endpoint. This resource is templated, which means, like `session` and `credential`, you can also create infrastructure-services of different types. + +--- +_Examples_ + + +## Create Docker Swarm infrastructure service + +{% include request_snippet.md file='api/infrastructure-service.sh' actions='POST' endpoint='/api/infrastructure-service-swarm' %} + +{% include code_snippet.md file='api/infrastructure-service-swarm.sh' language='shell' %} + +{% include response_snippet.md file='api/infrastructure-service-swarm-response.md' %} + + +## Create Kubernetes infrastructure service + +{% include request_snippet.md file='api/infrastructure-service-k8s.sh' actions='POST' endpoint='/api/infrastructure-service' %} + +{% include code_snippet.md file='api/infrastructure-service-k8s.sh' language='shell' %} + +{% include response_snippet.md file='api/infrastructure-service-k8s-response.md' %} + + +## Create S3 infrastructure service + +{% include request_snippet.md file='api/infrastructure-service-s3.sh' actions='POST' endpoint='/api/infrastructure-service' %} + +{% include code_snippet.md file='api/infrastructure-service-s3.sh' language='shell' %} + +{% include response_snippet.md file='api/infrastructure-service-s3-response.md' %} + + +## Create generic infrastructure service + +{% include request_snippet.md file='api/infrastructure-service.sh' actions='POST' endpoint='/api/infrastructure-service' %} + +{% include code_snippet.md file='api/infrastructure-service.sh' language='shell' %} + +{% include response_snippet.md file='api/infrastructure-service-response.md' %} + + +# infrastructure-service-group + +{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET DELETE' endpoint='/api/infrastructure-service-group/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} + +The `infrastructure-service-group` resource is a logical container for your infrastructure-service and respective credential and data resources. + + +--- +_Examples_ + + +## Create an infrastructure-service-group + +{% include request_snippet.md file='api/infrastructure-service-group.sh' actions='POST' endpoint='/api/infrastructure-service-group' %} + +{% include code_snippet.md file='api/infrastructure-service-group.sh' language='shell' %} + +{% include response_snippet.md file='api/infrastructure-service-group-response.md' %} + + diff --git a/docs/nuvla/advanced-usage/api/session.md b/docs/nuvla/advanced-usage/api/session.md new file mode 100644 index 0000000..1a378d0 --- /dev/null +++ b/docs/nuvla/advanced-usage/api/session.md @@ -0,0 +1,129 @@ +--- +layout: page +title: Session +nav_order: 3 +parent: API +has_children: false +--- + + +# Session + +{% include request_snippet.md actions='POST GET DELETE' endpoint='/api/session/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} + +The `session` resource allows you to: + + - use your credentials for authenticating with Nuvla + - Delete session (logout) + - switch group (act for a group) + - get your peers (users that share some groups with you) + +Users (clients) authenticate with the Nuvla server by referencing a `session-template` resource (to +identify the authentication method), providing values for the associated parameters, and then +creating a `session` resource via the templated 'add' pattern. + +A successful authentication attempt will return a token (as an HTTP cookie) that must be used in +subsequent interactions with the Nuvla server. + +The detailed process consists of the following steps: + +1. Browse the `session-template` resources to find the authentication method + that you want to use. Unless you have a browser-based client, you will + probably want to use either 'password' (username and password) or 'api-key' + (API key and secret). **Use of API keys and secrets is preferred over the + username and password for programmatic access.** + +2. Prepare a 'create' JSON document that references the `session-template` you + have chosen and provides the corresponding parameters (e.g. username and + password for 'password'). + +3. Post the 'create' document to the `session` collection URL. + +4. On a successful authentication request, a token will be returned allowing + access to the Nuvla resources as the authenticated user. **For convenience, + this token is returned as an HTTP cookie.** + +The authentication token (cookie) must be used in all subsequent requests to +the Nuvla server. The token (cookie) has a **limited lifetime** and you +must re-authenticate with the server when the token expires. + +## Attributes + + - _**active-claim**_: group or user id that you are claiming + - _**client-ip**_: your client ip as seen from nuvla server + - _**expiry**_: expiry date of your session + - _**method**_: method used to sign-in + - _**roles**_: string space separated of current roles applied to retrieve resources based on ACL + - _**identifier**_: username used to sign-in + - _**groups**_: string space separated groups + +--- + +## Examples + +**NOTE:** for later usage, we store the authenticated session in a file called _cookies_ + +Session is a templated resource. To create/add a new session, you have to refer to a +session-template resource. + +{% include request_snippet.md actions='GET' endpoint='/api/session-template' %} + +## Login with username and password + +{% include request_snippet.md file='api/session.sh' actions='POST' endpoint='/api/session' %} + +{% include code_snippet.md file='api/login.sh' language='shell' %} + +{% include response_snippet.md file='api/login-response.md' %} + + +## Login with API keys + +{% include request_snippet.md file='api/session.sh' actions='POST' endpoint='/api/session' %} + +{% include code_snippet.md file='api/login-apikey.sh' language='shell' %} + +{% include response_snippet.md file='api/login-response.md' %} + + +## Search session + +The search feature of `session` resources will only return the +`session` resource associated with your current session (or none at all if your +are not authenticated). This can be used to determine if you have an active +session and your associated identity and rights (e.g. groups). + + +{% include request_snippet.md actions='GET' endpoint='/api/session' %} + +{% include response_snippet.md file='api/sessions-response.md' %} + + +## Switch group operation + +When a user is in a group, he can ask to change his session to claim the group access. + + +{% include request_snippet.md actions='POST' endpoint='/api/session/689df57a-b217-43eb-bf94-85a0ab638e2c/switch-group' %} + +{% include code_snippet.md file='api/switch-group.sh' language='shell' %} + +{% include response_snippet.md file='api/session-switch-group-response.md' %} + + +## Get peers operation + +Get users that share some groups with you. + + +{% include request_snippet.md actions='POST' endpoint='/api/session/689df57a-b217-43eb-bf94-85a0ab638e2c/get-peers' %} + +{% include response_snippet.md file='api/session-get-peers-response.md' %} + + + +## Logout + +{% include request_snippet.md actions='DELETE' endpoint='/api/session/689df57a-b217-43eb-bf94-85a0ab638e2c' %} + +{% include response_snippet.md file='api/logout-response.md' %} diff --git a/docs/nuvla/advanced-usage/api/to-be-deleted.md b/docs/nuvla/advanced-usage/api/to-be-deleted.md new file mode 100644 index 0000000..8765c41 --- /dev/null +++ b/docs/nuvla/advanced-usage/api/to-be-deleted.md @@ -0,0 +1,46 @@ +--- +layout: page +title: To Be deleted +nav_order: 100 +parent: API +has_children: false +--- + + +## evidence-record + +{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET PUT DELETE' endpoint='/api/evidence-record/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} + +The `evidence-record` resource allows you to create and manage audit evidence records that can afterwards help you keep track of your infrastructures' compliance to certain standards and certification schemas. + +--- +_Examples_ + +### Create an evidence record + +{% include request_snippet.md file='api/evidence-record.sh' actions='POST' endpoint='/api/evidencerecord' %} + +{% include code_snippet.md file='api/evidencerecord.sh' language='shell' %} + +{% include response_snippet.md file='api/evidencerecord-response.md' %} + + + +## voucher + +{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET PUT DELETE' endpoint='/api/voucher/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} + +The `voucher` resource let's you create and manage digital vouchers, associated with any digital service provider, for better tracking and accounting of voucher consumption. + + +--- +_Examples_ + + +### Create a new voucher + +{% include request_snippet.md file='api/voucher.sh' actions='POST' endpoint='/api/voucher' %} + +{% include code_snippet.md file='api/voucher.sh' language='shell' %} + +{% include response_snippet.md file='api/voucher-response.md' %} diff --git a/docs/nuvla/advanced-usage/api/user.md b/docs/nuvla/advanced-usage/api/user.md new file mode 100644 index 0000000..ce762bb --- /dev/null +++ b/docs/nuvla/advanced-usage/api/user.md @@ -0,0 +1,35 @@ +--- +layout: page +title: User +nav_order: 4 +parent: API +has_children: false +--- + + +# user + +{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET PUT DELETE' endpoint='/api/user/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} + +The `user` resource allows you to create a new user account on Nuvla. + +--- +_Examples_ + + +## Create a user with an email and a password + +{% include request_snippet.md file='api/user_email_password.sh' actions='POST' endpoint='/api/user' %} + +{% include code_snippet.md file='api/user_email_password.sh' language='shell' %} + +{% include response_snippet.md file='api/user-email-password-response.md' %} + +Password must contain at least one uppercase character, one lowercase character, +one digit, one special character, and at least 8 characters in total. + +The creation of a user with `email-password` template does not require a session. + +The user will receive an email with a callback that he have to follow to activate his account. +After following the link, the state attribute of user document will transit from NEW to ACTIVE. + diff --git a/docs/nuvla/advanced-usage.md b/docs/nuvla/advanced-usage/index.md similarity index 100% rename from docs/nuvla/advanced-usage.md rename to docs/nuvla/advanced-usage/index.md diff --git a/docs/nuvla/installation/advanced-installation.md b/docs/nuvla/advanced-usage/installation/advanced-installation.md similarity index 99% rename from docs/nuvla/installation/advanced-installation.md rename to docs/nuvla/advanced-usage/installation/advanced-installation.md index 941acce..e43fd46 100644 --- a/docs/nuvla/installation/advanced-installation.md +++ b/docs/nuvla/advanced-usage/installation/advanced-installation.md @@ -4,7 +4,6 @@ title: Production Installation nav_order: 2 parent: Installation permalink: /nuvla/installation/production -grand_parent: Nuvla --- diff --git a/docs/nuvla/installation/example-apps.md b/docs/nuvla/advanced-usage/installation/example-apps.md similarity index 89% rename from docs/nuvla/installation/example-apps.md rename to docs/nuvla/advanced-usage/installation/example-apps.md index 6f7f44f..276cb19 100644 --- a/docs/nuvla/installation/example-apps.md +++ b/docs/nuvla/advanced-usage/installation/example-apps.md @@ -3,7 +3,6 @@ layout: page title: Example Apps nav_order: 3 parent: Installation -grand_parent: Nuvla permalink: /nuvla/installation/example-apps --- diff --git a/docs/nuvla/installation.md b/docs/nuvla/advanced-usage/installation/index.md similarity index 93% rename from docs/nuvla/installation.md rename to docs/nuvla/advanced-usage/installation/index.md index 5f72886..2534fd4 100644 --- a/docs/nuvla/installation.md +++ b/docs/nuvla/advanced-usage/installation/index.md @@ -1,12 +1,12 @@ --- layout: page title: Installation -nav_order: 1 -parent: Nuvla +nav_order: 12 +parent: Advanced Usage has_children: true -permalink: /nuvla/installation --- + The following diagram shows the main blocks of the Nuvla Architecture. ![Nuvla Architecture](/assets/img/architecture.png) diff --git a/docs/nuvla/installation/operation-maintenance.md b/docs/nuvla/advanced-usage/installation/operation-maintenance.md similarity index 99% rename from docs/nuvla/installation/operation-maintenance.md rename to docs/nuvla/advanced-usage/installation/operation-maintenance.md index 07cc089..1e882e9 100644 --- a/docs/nuvla/installation/operation-maintenance.md +++ b/docs/nuvla/advanced-usage/installation/operation-maintenance.md @@ -3,7 +3,6 @@ layout: page title: Operate & Maintain nav_order: 4 parent: Installation -grand_parent: Nuvla permalink: /nuvla/installation/operation-maintenance --- diff --git a/docs/nuvla/installation/quickstart.md b/docs/nuvla/advanced-usage/installation/quickstart.md similarity index 99% rename from docs/nuvla/installation/quickstart.md rename to docs/nuvla/advanced-usage/installation/quickstart.md index 249d9d5..ad935c9 100644 --- a/docs/nuvla/installation/quickstart.md +++ b/docs/nuvla/advanced-usage/installation/quickstart.md @@ -3,7 +3,6 @@ layout: page title: Quickstart nav_order: 1 parent: Installation -grand_parent: Nuvla --- Here's a simple guide to quickly install Nuvla for evaluation purposes. So if you're looking for quickly trying out Nuvla, you're at the right place. However, if you're looking for a robust production level installation, you probably want to look at [the production deployment page](/nuvla/installation/production). diff --git a/docs/nuvla/advanced-usage/manage-data.md b/docs/nuvla/advanced-usage/manage-data.md index 492a3d5..1983757 100644 --- a/docs/nuvla/advanced-usage/manage-data.md +++ b/docs/nuvla/advanced-usage/manage-data.md @@ -3,7 +3,7 @@ layout: page title: Manage Data parent: Advanced Usage grand_parent: Nuvla -nav_order: 1 +nav_order: 4 permalink: /nuvla/advanced-usage/manage-data --- diff --git a/docs/nuvla/nuvla.md b/docs/nuvla/index.md similarity index 100% rename from docs/nuvla/nuvla.md rename to docs/nuvla/index.md diff --git a/docs/nuvla/user-guide/api.md b/docs/nuvla/user-guide/api.md deleted file mode 100644 index a9df300..0000000 --- a/docs/nuvla/user-guide/api.md +++ /dev/null @@ -1,437 +0,0 @@ ---- -layout: page -title: API -parent: User Guide -grand_parent: Nuvla -nav_order: 12 -permalink: /nuvla/api ---- - -- [REST API](#rest-api) - * [Understanding the Nuvla REST API output format](#understanding-the-nuvla-rest-api-output-format) - * [API Syntax](#api-syntax) - * [Resources](#resources) - + [cloud-entry-point](#cloud-entry-point) - + [Get the cloud entry point](#get-the-cloud-entry-point) - + [credential](#credential) - + [API key credential](#generate-an-api-key-credential) - + [Docker Swarm token credential](#docker-swarm-token-credential) - + [Infrastructure Service S3 credential](#infrastructure-service-s3-credential) - + [Infrastructure Service Docker Swarm HTTP API credential](#infrastructure-service-docker-swarm-http-api-credential) - + [Infrastructure Service Kubernetes HTTP API credential](#infrastructure-service-kubernetes-http-api-credential) - + [deployment](#deployment) - + [Start/Stop an application](#startstop-an-application) - + [evidence-record](#evidence-record) - + [Create an evidence record](#create-an-evidence-record) - + [infrastructure-service](#infrastructure-service) - + [Create Docker Swarm infrastructure service](#create-docker-swarm-infrastructure-service) - + [Create Kubernetes infrastructure service](#create-kubernetes-infrastructure-service) - + [Create S3 infrastructure service](#create-s3-infrastructure-service) - + [Create generic infrastructure service](#create-generic-infrastructure-service) - + [infrastructure-service-group](#infrastructure-service-group) - + [Create an infrastructure-service-group](#create-an-infrastructure-service-group) - + [session](#session) - + [Login with username and password](#login-with-username-and-password) - + [Login with API keys](#login-with-api-keys) - + [user](#user) - + [Create a user with an email and a password](#create-a-user-with-an-email-and-a-password) - + [voucher](#voucher) - + [Create a new voucher](#create-a-new-voucher) -- [Python API](#python-api) - - -# REST API - -Nuvla provides a uniform and extensible HTTP-based RESTful API, for the management of Nuvla resources. A Nuvla resource can be anything you can perform an action on, through Nuvla, like your own user profile, a Nuvla application, credentials, etc. - -Users have at their disposal all the usual CRUD (Create, Read, Update, Delete) operations, plus Searching and Querying. - - -| Action | HTTP Method | Target | -| --- | --- | --- | -| Search | GET or PUT | resource collection | -| Add (create) | POST | resource collection | -| Read | GET | resource | -| Edit (update) | PUT | resource | -| Delete | DELETE | resource | - -Finally, due to its versatility, 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/` - - - **GET** a specific resource: - - `GET /api//` - - - **CREATE** a new resource: - - ``` -POST /api/ - HEADERS Content-type:application/json - DATA - ``` - - - **EDIT** an existing resource: - - ``` -PUT /api// - HEADERS Content-type:application/json - DATA - ``` - - - **DELETE** a resource: - - `DELETE /api//` - - - -## Understanding the Nuvla REST API output format - -All the Nuvla API calls 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 - - _**updated**_: timestamp of the last update, defined by the API server - - _**resource-type**_: type of resource, defined by the API server - - _**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 - - -## API Syntax - -The Nuvla REST API endpoints are constructed with the following pattern: - -`/api////` - -where - - - `` is the Kebab Case name of the resource collection you're accessing, - - `` is the unique identifier for the specific resource you're managing, - - `` 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/?param=value¶m=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"`

`?filter=people/gender!="male" and people/age>=21`

`?filter=application-name^="my-app-"` | -| `orderby` | To order the returned resources by the specified attribute | `?orderby=created:desc`

`?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` | - - -## Resources - -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. - - -### 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' %} - - -### credential - -{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET PUT DELETE' endpoint='/api/credential/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} - -The `credential` resource is used to save all the credentials necessary to -manage your Nuvla resources. From API keys, to Container Orchestration Engine -credentials, TLS certificates, etc. Most of the credentials are expected to be -provided by the user, some are generated by Nuvla (e.g. API key). - ---- -_Examples_ - -##### Generate an API key credential - -{% include request_snippet.md file='api/credential-apikey.sh' actions='POST' endpoint='/api/credential' %} - -{% include code_snippet.md file='api/credential-apikey.sh' language='shell' %} - -{% include response_snippet.md file='api/credential-apikey-response.md' %} - - - -##### Docker Swarm token credential - -{% include request_snippet.md file='api/credential-swarmtoken.sh' actions='POST' endpoint='/api/credential' %} - -{% include code_snippet.md file='api/credential-swarmtoken.sh' language='shell' %} - -{% include response_snippet.md file='api/credential-swarmtoken-response.md' %} - - -##### Infrastructure Service S3 credential - -{% include request_snippet.md file='api/credential-s3.sh' actions='POST' endpoint='/api/credential' %} - -{% include code_snippet.md file='api/credential-s3.sh' language='shell' %} - -{% include response_snippet.md file='api/credential-s3-response.md' %} - - -##### Infrastructure Service Docker Swarm HTTP API credential - -{% include request_snippet.md file='api/credential-swarm.sh' actions='POST' endpoint='/api/credential' %} - -{% include code_snippet.md file='api/credential-swarm.sh' language='shell' %} - -{% include response_snippet.md file='api/credential-swarm-response.md' %} - - -##### Infrastructure Service Kubernetes HTTP API credential - -{% include request_snippet.md file='api/credential-kubernetes.sh' actions='POST' endpoint='/api/credential' %} - -{% include code_snippet.md file='api/credential-kubernetes.sh' language='shell' %} - -{% include response_snippet.md file='api/credential-kubernetes-response.md' %} - - -### deployment - -{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET PUT DELETE' endpoint='/api/deployment/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} - -The `deployment` resource allows you to deploy an instance of a `module`. - ---- -_Examples_ - -##### Start/Stop an application - -{% include request_snippet.md file='api/deployment.sh' actions='POST PUT GET' endpoint='/api/deployment' %} - -{% include code_snippet.md file='api/deployment.sh' language='shell' %} - -{% include response_snippet.md file='api/deployment-response.md' %} - - - - -### evidence-record - -{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET PUT DELETE' endpoint='/api/evidence-record/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} - -The `evidence-record` resource allows you to create and manage audit evidence records that can afterwards help you keep track of your infrastructures' compliance to certain standards and certification schemas. - ---- -_Examples_ - -##### Create an evidence record - -{% include request_snippet.md file='api/evidence-record.sh' actions='POST' endpoint='/api/evidencerecord' %} - -{% include code_snippet.md file='api/evidencerecord.sh' language='shell' %} - -{% include response_snippet.md file='api/evidencerecord-response.md' %} - - - - -### infrastructure-service - -{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET PUT DELETE' endpoint='/api/infrastructure-service/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} - -The `infrastructure-service` resource represents any manageable service with a working endpoint. This resource is templated, which means, like `session` and `credential`, you can also create infrastructure-services of different types. - ---- -_Examples_ - - -##### Create Docker Swarm infrastructure service - -{% include request_snippet.md file='api/infrastructure-service.sh' actions='POST' endpoint='/api/infrastructure-service-swarm' %} - -{% include code_snippet.md file='api/infrastructure-service-swarm.sh' language='shell' %} - -{% include response_snippet.md file='api/infrastructure-service-swarm-response.md' %} - - -##### Create Kubernetes infrastructure service - -{% include request_snippet.md file='api/infrastructure-service-k8s.sh' actions='POST' endpoint='/api/infrastructure-service' %} - -{% include code_snippet.md file='api/infrastructure-service-k8s.sh' language='shell' %} - -{% include response_snippet.md file='api/infrastructure-service-k8s-response.md' %} - - -##### Create S3 infrastructure service - -{% include request_snippet.md file='api/infrastructure-service-s3.sh' actions='POST' endpoint='/api/infrastructure-service' %} - -{% include code_snippet.md file='api/infrastructure-service-s3.sh' language='shell' %} - -{% include response_snippet.md file='api/infrastructure-service-s3-response.md' %} - - -##### Create generic infrastructure service - -{% include request_snippet.md file='api/infrastructure-service.sh' actions='POST' endpoint='/api/infrastructure-service' %} - -{% include code_snippet.md file='api/infrastructure-service.sh' language='shell' %} - -{% include response_snippet.md file='api/infrastructure-service-response.md' %} - - -### infrastructure-service-group - -{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET DELETE' endpoint='/api/infrastructure-service-group/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} - -The `infrastructure-service-group` resource is a logical container for your infrastructure-service and respective credential and data resources. - - ---- -_Examples_ - - -##### Create an infrastructure-service-group - -{% include request_snippet.md file='api/infrastructure-service-group.sh' actions='POST' endpoint='/api/infrastructure-service-group' %} - -{% include code_snippet.md file='api/infrastructure-service-group.sh' language='shell' %} - -{% include response_snippet.md file='api/infrastructure-service-group-response.md' %} - - - - -### session - -{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET DELETE' endpoint='/api/session/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} - -The `session` resource allows you to use your credentials for authenticating with Nuvla. - -**NOTE:** for later usage, we store the authenticated session in a file called _cookies_ - ---- -_Examples_ - - -##### Login with username and password - -{% include request_snippet.md file='api/session.sh' actions='POST' endpoint='/api/session' %} - -{% include code_snippet.md file='api/login.sh' language='shell' %} - -{% include response_snippet.md file='api/login-response.md' %} - - -##### Login with API keys - -{% include request_snippet.md file='api/session.sh' actions='POST' endpoint='/api/session' %} - -{% include code_snippet.md file='api/login_apikey.sh' language='shell' %} - -{% include response_snippet.md file='api/login-response.md' %} - -### user - -{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET PUT DELETE' endpoint='/api/user/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} - -The `user` resource allows you to create a new user account on Nuvla. - ---- -_Examples_ - - -##### Create a user with an email and a password - -{% include request_snippet.md file='api/user_email_password.sh' actions='POST' endpoint='/api/user' %} - -{% include code_snippet.md file='api/user_email_password.sh' language='shell' %} - -{% include response_snippet.md file='api/user-email-password-response.md' %} - -Password must contain at least one uppercase character, one lowercase character, -one digit, one special character, and at least 8 characters in total. - -The creation of a user with `email-password` template does not require a session. - -The user will receive an email with a callback that he have to follow to activate his account. -After following the link, the state attribute of user document will transit from NEW to ACTIVE. - - -### voucher - -{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET PUT DELETE' endpoint='/api/voucher/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} - -The `voucher` resource let's you create and manage digital vouchers, associated with any digital service provider, for better tracking and accounting of voucher consumption. - - ---- -_Examples_ - - -##### Create a new voucher - -{% include request_snippet.md file='api/voucher.sh' actions='POST' endpoint='/api/voucher' %} - -{% include code_snippet.md file='api/voucher.sh' language='shell' %} - -{% include response_snippet.md file='api/voucher-response.md' %} - - -# Python API - -(coming soon...) diff --git a/docs/nuvla/user-guide.md b/docs/nuvla/user-guide/index.md similarity index 86% rename from docs/nuvla/user-guide.md rename to docs/nuvla/user-guide/index.md index fc0be24..c7c1474 100644 --- a/docs/nuvla/user-guide.md +++ b/docs/nuvla/user-guide/index.md @@ -8,7 +8,7 @@ has_children: true # Nuvla - What is it? -Nuvla is a secured edge-to-cloud (and back) management platform that enables near-data AI for a connected world. +Nuvlaa is a secured edge-to-cloud (and back) management platform that enables near-data AI for a connected world. The container native platform supports all forms of infrastructure: public cloud, private cloud and bare metal infrastructures, as well as edge (with our NuvlaBox).