From 0b9433141df0dcc4ed39cf0d044220ba5db861ab Mon Sep 17 00:00:00 2001 From: khaled basbous Date: Tue, 21 Dec 2021 16:13:07 +0100 Subject: [PATCH 1/3] wip --- docs/nuvla/installation.md | 2 +- docs/nuvla/user-guide/api.md | 437 ------------------ docs/nuvla/user-guide/api/credential.md | 99 ++++ docs/nuvla/user-guide/api/deployment.md | 24 + docs/nuvla/user-guide/api/index.md | 15 + .../api/infrastructure-service-group.md | 28 ++ .../user-guide/api/infrastructure-service.md | 74 +++ docs/nuvla/user-guide/api/principle.md | 216 +++++++++ docs/nuvla/user-guide/api/session.md | 37 ++ docs/nuvla/user-guide/api/to-be-deleted.md | 46 ++ docs/nuvla/user-guide/api/user.md | 34 ++ .../{user-guide.md => user-guide/index.md} | 2 +- 12 files changed, 575 insertions(+), 439 deletions(-) delete mode 100644 docs/nuvla/user-guide/api.md create mode 100644 docs/nuvla/user-guide/api/credential.md create mode 100644 docs/nuvla/user-guide/api/deployment.md create mode 100644 docs/nuvla/user-guide/api/index.md create mode 100644 docs/nuvla/user-guide/api/infrastructure-service-group.md create mode 100644 docs/nuvla/user-guide/api/infrastructure-service.md create mode 100644 docs/nuvla/user-guide/api/principle.md create mode 100644 docs/nuvla/user-guide/api/session.md create mode 100644 docs/nuvla/user-guide/api/to-be-deleted.md create mode 100644 docs/nuvla/user-guide/api/user.md rename docs/nuvla/{user-guide.md => user-guide/index.md} (86%) diff --git a/docs/nuvla/installation.md b/docs/nuvla/installation.md index 5f72886..aa941fd 100644 --- a/docs/nuvla/installation.md +++ b/docs/nuvla/installation.md @@ -1,7 +1,7 @@ --- layout: page title: Installation -nav_order: 1 +nav_order: 12 parent: Nuvla has_children: true permalink: /nuvla/installation 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/api/credential.md b/docs/nuvla/user-guide/api/credential.md new file mode 100644 index 0000000..c9fc7b6 --- /dev/null +++ b/docs/nuvla/user-guide/api/credential.md @@ -0,0 +1,99 @@ +--- +layout: page +title: Credential +nav_order: 3 +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/user-guide/api/deployment.md b/docs/nuvla/user-guide/api/deployment.md new file mode 100644 index 0000000..4fc713b --- /dev/null +++ b/docs/nuvla/user-guide/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/user-guide/api/index.md b/docs/nuvla/user-guide/api/index.md new file mode 100644 index 0000000..575989a --- /dev/null +++ b/docs/nuvla/user-guide/api/index.md @@ -0,0 +1,15 @@ +--- +layout: page +title: API +parent: User Guide +nav_order: 1 +has_children: true +permalink: /nuvla/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, Querying, Bulk delete and Bulk actions. + diff --git a/docs/nuvla/user-guide/api/infrastructure-service-group.md b/docs/nuvla/user-guide/api/infrastructure-service-group.md new file mode 100644 index 0000000..b6b62f6 --- /dev/null +++ b/docs/nuvla/user-guide/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/user-guide/api/infrastructure-service.md b/docs/nuvla/user-guide/api/infrastructure-service.md new file mode 100644 index 0000000..a1aeba5 --- /dev/null +++ b/docs/nuvla/user-guide/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/user-guide/api/principle.md b/docs/nuvla/user-guide/api/principle.md new file mode 100644 index 0000000..ce5b994 --- /dev/null +++ b/docs/nuvla/user-guide/api/principle.md @@ -0,0 +1,216 @@ +--- +layout: page +title: Principle +nav_order: 1 +parent: API +has_children: false +--- + +# API Syntax + + +| 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 + ``` + + - **DELETE** a resource: + + `DELETE /api//` + + - **SEARCH** 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. | + + +## 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/user-guide/api/session.md b/docs/nuvla/user-guide/api/session.md new file mode 100644 index 0000000..21ada23 --- /dev/null +++ b/docs/nuvla/user-guide/api/session.md @@ -0,0 +1,37 @@ +--- +layout: page +title: Session +nav_order: 1 +parent: API +has_children: false +--- + + +# 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' %} diff --git a/docs/nuvla/user-guide/api/to-be-deleted.md b/docs/nuvla/user-guide/api/to-be-deleted.md new file mode 100644 index 0000000..8765c41 --- /dev/null +++ b/docs/nuvla/user-guide/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/user-guide/api/user.md b/docs/nuvla/user-guide/api/user.md new file mode 100644 index 0000000..3998132 --- /dev/null +++ b/docs/nuvla/user-guide/api/user.md @@ -0,0 +1,34 @@ +--- +layout: page +title: User +nav_order: 2 +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/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). From 80e01438b927b7a4b42f126bb2f9a4ad306a4098 Mon Sep 17 00:00:00 2001 From: khaled basbous Date: Wed, 22 Dec 2021 14:33:43 +0100 Subject: [PATCH 2/3] Add Nuvladocs logo, session api with attributes and operations, minor fixes and refactor --- docs/_config.yml | 2 +- .../api/{login_apikey.sh => login-apikey.sh} | 2 +- .../api/session-get-peers-response.md | 7 ++ .../api/session-switch-group-response.md | 32 +++++++ docs/_includes/api/sessions-response.md | 53 +++++++++++ docs/_includes/api/switch-group.sh | 3 + docs/assets/img/nuvladocs-logo.png | Bin 0 -> 19445 bytes .../advanced-usage/api/cloud-entry-point.md | 29 ++++++ .../api/common-design.md} | 28 +----- .../api/credential.md | 2 +- .../api/deployment.md | 0 .../api/index.md | 3 +- .../api/infrastructure-service-group.md | 0 .../api/infrastructure-service.md | 0 docs/nuvla/advanced-usage/api/session.md | 84 ++++++++++++++++++ .../api/to-be-deleted.md | 0 .../api/user.md | 3 +- .../index.md} | 0 .../installation/advanced-installation.md | 1 - .../installation/example-apps.md | 1 - .../installation/index.md} | 4 +- .../installation/operation-maintenance.md | 1 - .../installation/quickstart.md | 1 - docs/nuvla/advanced-usage/manage-data.md | 2 +- docs/nuvla/{nuvla.md => index.md} | 0 docs/nuvla/user-guide/api/session.md | 37 -------- 26 files changed, 220 insertions(+), 75 deletions(-) rename docs/_includes/api/{login_apikey.sh => login-apikey.sh} (88%) create mode 100644 docs/_includes/api/session-get-peers-response.md create mode 100644 docs/_includes/api/session-switch-group-response.md create mode 100644 docs/_includes/api/sessions-response.md create mode 100644 docs/_includes/api/switch-group.sh create mode 100644 docs/assets/img/nuvladocs-logo.png create mode 100644 docs/nuvla/advanced-usage/api/cloud-entry-point.md rename docs/nuvla/{user-guide/api/principle.md => advanced-usage/api/common-design.md} (90%) rename docs/nuvla/{user-guide => advanced-usage}/api/credential.md (99%) rename docs/nuvla/{user-guide => advanced-usage}/api/deployment.md (100%) rename docs/nuvla/{user-guide => advanced-usage}/api/index.md (92%) rename docs/nuvla/{user-guide => advanced-usage}/api/infrastructure-service-group.md (100%) rename docs/nuvla/{user-guide => advanced-usage}/api/infrastructure-service.md (100%) create mode 100644 docs/nuvla/advanced-usage/api/session.md rename docs/nuvla/{user-guide => advanced-usage}/api/to-be-deleted.md (100%) rename docs/nuvla/{user-guide => advanced-usage}/api/user.md (98%) rename docs/nuvla/{advanced-usage.md => advanced-usage/index.md} (100%) rename docs/nuvla/{ => advanced-usage}/installation/advanced-installation.md (99%) rename docs/nuvla/{ => advanced-usage}/installation/example-apps.md (89%) rename docs/nuvla/{installation.md => advanced-usage/installation/index.md} (95%) rename docs/nuvla/{ => advanced-usage}/installation/operation-maintenance.md (99%) rename docs/nuvla/{ => advanced-usage}/installation/quickstart.md (99%) rename docs/nuvla/{nuvla.md => index.md} (100%) delete mode 100644 docs/nuvla/user-guide/api/session.md 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/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/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..1fdb24f --- /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 0000000000000000000000000000000000000000..633a58b2f36c896e7688daaeca8d8aeed474285f GIT binary patch literal 19445 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 literal 0 HcmV?d00001 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/user-guide/api/principle.md b/docs/nuvla/advanced-usage/api/common-design.md similarity index 90% rename from docs/nuvla/user-guide/api/principle.md rename to docs/nuvla/advanced-usage/api/common-design.md index ce5b994..5eb397f 100644 --- a/docs/nuvla/user-guide/api/principle.md +++ b/docs/nuvla/advanced-usage/api/common-design.md @@ -1,12 +1,12 @@ --- layout: page -title: Principle +title: Common Design nav_order: 1 parent: API -has_children: false +has_children: true --- -# API Syntax +# Common Design | Action | HTTP Method | Target | @@ -192,25 +192,3 @@ E.g. tags field is defined as an array of string. In case we would like to searc | 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. | - - -## 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/user-guide/api/credential.md b/docs/nuvla/advanced-usage/api/credential.md similarity index 99% rename from docs/nuvla/user-guide/api/credential.md rename to docs/nuvla/advanced-usage/api/credential.md index c9fc7b6..c693b77 100644 --- a/docs/nuvla/user-guide/api/credential.md +++ b/docs/nuvla/advanced-usage/api/credential.md @@ -1,7 +1,7 @@ --- layout: page title: Credential -nav_order: 3 +nav_order: 4 parent: API has_children: false --- diff --git a/docs/nuvla/user-guide/api/deployment.md b/docs/nuvla/advanced-usage/api/deployment.md similarity index 100% rename from docs/nuvla/user-guide/api/deployment.md rename to docs/nuvla/advanced-usage/api/deployment.md diff --git a/docs/nuvla/user-guide/api/index.md b/docs/nuvla/advanced-usage/api/index.md similarity index 92% rename from docs/nuvla/user-guide/api/index.md rename to docs/nuvla/advanced-usage/api/index.md index 575989a..883b263 100644 --- a/docs/nuvla/user-guide/api/index.md +++ b/docs/nuvla/advanced-usage/api/index.md @@ -1,10 +1,9 @@ --- layout: page title: API -parent: User Guide +parent: Advanced Usage nav_order: 1 has_children: true -permalink: /nuvla/api --- # REST API diff --git a/docs/nuvla/user-guide/api/infrastructure-service-group.md b/docs/nuvla/advanced-usage/api/infrastructure-service-group.md similarity index 100% rename from docs/nuvla/user-guide/api/infrastructure-service-group.md rename to docs/nuvla/advanced-usage/api/infrastructure-service-group.md diff --git a/docs/nuvla/user-guide/api/infrastructure-service.md b/docs/nuvla/advanced-usage/api/infrastructure-service.md similarity index 100% rename from docs/nuvla/user-guide/api/infrastructure-service.md rename to docs/nuvla/advanced-usage/api/infrastructure-service.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..ca7d792 --- /dev/null +++ b/docs/nuvla/advanced-usage/api/session.md @@ -0,0 +1,84 @@ +--- +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. +Extra operations allows you to get the claims of a group and to get a list of your peers (users that share some groups with you). + + +## 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_ + + +## 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 + +Retrieve of session collection will return always zero or one resource back. A user can only have +one active session at a time. + + +{% 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' %} + diff --git a/docs/nuvla/user-guide/api/to-be-deleted.md b/docs/nuvla/advanced-usage/api/to-be-deleted.md similarity index 100% rename from docs/nuvla/user-guide/api/to-be-deleted.md rename to docs/nuvla/advanced-usage/api/to-be-deleted.md diff --git a/docs/nuvla/user-guide/api/user.md b/docs/nuvla/advanced-usage/api/user.md similarity index 98% rename from docs/nuvla/user-guide/api/user.md rename to docs/nuvla/advanced-usage/api/user.md index 3998132..ce762bb 100644 --- a/docs/nuvla/user-guide/api/user.md +++ b/docs/nuvla/advanced-usage/api/user.md @@ -1,7 +1,7 @@ --- layout: page title: User -nav_order: 2 +nav_order: 4 parent: API has_children: false --- @@ -32,3 +32,4 @@ 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 95% rename from docs/nuvla/installation.md rename to docs/nuvla/advanced-usage/installation/index.md index aa941fd..2534fd4 100644 --- a/docs/nuvla/installation.md +++ b/docs/nuvla/advanced-usage/installation/index.md @@ -2,11 +2,11 @@ layout: page title: Installation nav_order: 12 -parent: Nuvla +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/session.md b/docs/nuvla/user-guide/api/session.md deleted file mode 100644 index 21ada23..0000000 --- a/docs/nuvla/user-guide/api/session.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -layout: page -title: Session -nav_order: 1 -parent: API -has_children: false ---- - - -# 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' %} From 2241b01b6d9a9f902f066088636257ec2ae183be Mon Sep 17 00:00:00 2001 From: khaled basbous Date: Wed, 22 Dec 2021 16:52:31 +0100 Subject: [PATCH 3/3] group api doc --- docs/_includes/api/group-response.md | 7 +++ docs/_includes/api/group.sh | 10 ++++ docs/_includes/api/invite-response.md | 7 +++ docs/_includes/api/invite.sh | 3 ++ docs/_includes/api/logout-response.md | 7 +++ docs/_includes/api/switch-group.sh | 2 +- .../nuvla/advanced-usage/api/common-design.md | 5 +- docs/nuvla/advanced-usage/api/credential.md | 2 +- docs/nuvla/advanced-usage/api/group.md | 52 ++++++++++++++++++ docs/nuvla/advanced-usage/api/session.md | 53 +++++++++++++++++-- 10 files changed, 141 insertions(+), 7 deletions(-) create mode 100644 docs/_includes/api/group-response.md create mode 100644 docs/_includes/api/group.sh create mode 100644 docs/_includes/api/invite-response.md create mode 100644 docs/_includes/api/invite.sh create mode 100644 docs/_includes/api/logout-response.md create mode 100644 docs/nuvla/advanced-usage/api/group.md 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/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/switch-group.sh b/docs/_includes/api/switch-group.sh index 1fdb24f..4656ee0 100644 --- a/docs/_includes/api/switch-group.sh +++ b/docs/_includes/api/switch-group.sh @@ -1,3 +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"} + {"claim": "group/x"} ''' diff --git a/docs/nuvla/advanced-usage/api/common-design.md b/docs/nuvla/advanced-usage/api/common-design.md index 5eb397f..dc69baf 100644 --- a/docs/nuvla/advanced-usage/api/common-design.md +++ b/docs/nuvla/advanced-usage/api/common-design.md @@ -71,11 +71,14 @@ Here are a few examples on how to construct the different HTTP requests: 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//` - - **SEARCH** on resources: + - **QUERY** on resources: `GET /api/?param=value¶m=value` diff --git a/docs/nuvla/advanced-usage/api/credential.md b/docs/nuvla/advanced-usage/api/credential.md index c693b77..57fc248 100644 --- a/docs/nuvla/advanced-usage/api/credential.md +++ b/docs/nuvla/advanced-usage/api/credential.md @@ -1,7 +1,7 @@ --- layout: page title: Credential -nav_order: 4 +nav_order: 5 parent: API has_children: false --- 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/session.md b/docs/nuvla/advanced-usage/api/session.md index ca7d792..1a378d0 100644 --- a/docs/nuvla/advanced-usage/api/session.md +++ b/docs/nuvla/advanced-usage/api/session.md @@ -11,9 +11,41 @@ has_children: false {% 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. -Extra operations allows you to get the claims of a group and to get a list of your peers (users that share some groups with you). +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 @@ -31,6 +63,10 @@ Extra operations allows you to get the claims of a group and to get a list of yo **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 @@ -52,8 +88,10 @@ Extra operations allows you to get the claims of a group and to get a list of yo ## Search session -Retrieve of session collection will return always zero or one resource back. A user can only have -one active session at a time. +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' %} @@ -82,3 +120,10 @@ Get users that share some groups with you. {% 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' %}