From f0ff0fd3337158cb44d60a2d701f6ade13773627 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Tue, 6 Sep 2016 11:43:19 +0200 Subject: [PATCH 01/54] REST service: api-description draft --- .../snippet_sharing/api-description.apib | 410 ++++++++++++++++++ 1 file changed, 410 insertions(+) create mode 100644 doc/rest_api/snippet_sharing/api-description.apib diff --git a/doc/rest_api/snippet_sharing/api-description.apib b/doc/rest_api/snippet_sharing/api-description.apib new file mode 100644 index 00000000000..8d94d504e6a --- /dev/null +++ b/doc/rest_api/snippet_sharing/api-description.apib @@ -0,0 +1,410 @@ +FORMAT: 1.0 + +# REST service API for sharing configuration snippets + +This is a description of the API provided by the REST service that can be used to share, search and download configuration snippets. + + +# API Description [/] + +## List API methods [GET] + +Returns an overview of available API methods with required parameters and a description. + ++ Response 200 (text/html; charset=utf-8) + + + +# Authentication endpoint [/auth] + +## Authenticate [POST] + +The API will try to authenticate the user by the submitted credentials. In case of success a session token (JWT) will be returned, which can be used for further requests to the API. + ++ Request (application/x-www-form-urlencoded) + + Attributes + + username: the_username (string, required) + + password: aSecretPassword (string, required) + + + Schema + + { + "type": "object", + "properties": { + "username": { + "description": "Name of the user that wants to authenticate", + "type": "string" + }, + "password": { + "description": "Password for the username in question", + "type": "string" + } + }, + "required": [ + "username", + "password" + ], + "additionalProperties": false + } + ++ Response 200 (application/json) + + Body + + { + "status": 200, + "token": "eyJ...Q2tY=" + } + + + Schema + + { + "type": "object", + "properties": { + "status": { + "description": "HTTP status code", + "type": "integer", + "minimum": 0 + }, + "token": { + "description": "Session token to be used as authentication for further requests.", + "type": "string" + } + }, + "required": [ + "status", + "token" + ], + "additionalProperties": false + } + ++ Response 401 (application/json) + + Body + + { + "status": 401, + "error": "Unauthorized", + "message": "You have to supply an username and a password.", + "loca": "AUTH_NEED_USERNAME_PASSWORD" + } + + + Schema + + { + "type": "object", + "properties": { + "status": { + "description": "HTTP status code", + "type": "integer", + "minimum": 0 + }, + "error": { + "description": "Textual description of HTTP status code", + "type": "string" + }, + "message": { + "description": "Detailed information about the error.", + "type": "string" + }, + "loca": { + "description": "Unique message token that can be used for localization in a frontend application.", + "type": "string" + } + }, + "required": [ + "status", + "message", + "loca" + ], + "additionalProperties": false + } + + +## Retrieve current user [GET /user] + +Retrieves the currently authenticated users details. + ++ Response 200 (application/json) + + Body + + { + "status": 200, + "username": "the_username", + "rank": 1 + } + + + Schema + + { + "type": "object", + "properties": { + "status": { + "description": "HTTP status code", + "type": "integer", + "minimum": 0 + }, + "username": { + "description": "The authenticated users name", + "type": "string" + }, + "rank": { + "description": "The authenticated users rank", + "type": "integer" + } + }, + "required": [ + "status", + "username", + "rank" + ], + "additionalProperties": false + } + ++ Response 401 (application/json) + + Body + + { + "status": 401, + "error": "Unauthorized", + "message": "You need to be authenticated to perform this action.", + "loca": "NEED_AUTHENTICATION" + } + + + Schema + + { + "type": "object", + "properties": { + "status": { + "description": "HTTP status code", + "type": "integer", + "minimum": 0 + }, + "error": { + "description": "Textual description of HTTP status code", + "type": "string" + }, + "message": { + "description": "Detailed information about the error.", + "type": "string" + }, + "loca": { + "description": "Unique message token that can be used for localization in a frontend application.", + "type": "string" + } + }, + "required": [ + "status", + "message", + "loca" + ], + "additionalProperties": false + } + + +## Register [POST /register] + +This method can be used to register for the service. An user account will grant access to more functionality. + ++ Request Register via form (application/x-www-form-urlencoded) + + Attributes + + username: the_username (string, required) + + The username must be between 3 and 20 signs long and may contain only letters a-z (lower- and upper-case), the numbers 0-9 and dots (.) as well as dashes (-). + + + password: somePassword (string, required) - A non-empty password + + email: an@email.com (string, required) - A valid email address + ++ Response 200 (application/json) + + Body + + { + "status":200, + "message":"Your account has been created successfully!", + "loca":"AUTH_REGISTER_USER_CREATED_SUCCESSFULLY" + } + + + Schema + + { + "type": "object", + "properties": { + "status": { + "description": "HTTP status code", + "type": "integer", + "minimum": 0 + }, + "error": { + "description": "Textual description of HTTP status code", + "type": "string" + }, + "message": { + "description": "Detailed information about the error.", + "type": "string" + }, + "loca": { + "description": "Unique message token that can be used for localization in a frontend application.", + "type": "string" + } + }, + "required": [ + "status", + "message", + "loca" + ], + "additionalProperties": false + } + ++ Response 400 (application/json) + + Body + + { + "status":400, + "error":"Bad Request", + "message":"You have to supply an username, a password and an email.", + "loca":"AUTH_REGISTER_NEED_USERNAME_PASSWORD_EMAIL" + } + + + Schema + + { + "type": "object", + "properties": { + "status": { + "description": "HTTP status code", + "type": "integer", + "minimum": 0 + }, + "error": { + "description": "Textual description of HTTP status code", + "type": "string" + }, + "message": { + "description": "Detailed information about the error.", + "type": "string" + }, + "loca": { + "description": "Unique message token that can be used for localization in a frontend application.", + "type": "string" + } + }, + "required": [ + "status", + "message", + "loca" + ], + "additionalProperties": false + } + + +## Set user rank [POST /setrank] + +This method can be used to set the rank of an user. Only users with a rank high enough have the privilegue to set the rank of users. + ++ Request Set rank via form (application/x-www-form-urlencoded) + + Attributes + + username: the_username (string, required) + + rank: 3 (number, required) + + + Schema + + { + "type": "object", + "properties": { + "username": { + "description": "The users name who shall be changed", + "type": "string" + }, + "rank": { + "description": "The new rank to apply to the user", + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "username", + "rank" + ], + "additionalProperties": false + } + ++ Response 200 (application/json) + + Body + + { + "status": 200, + "message": "The rank has been set successfully.", + "loca": "USER_SET_RANK_SUCCESSFULLY" + } + + + Schema + + { + "type": "object", + "properties": { + "status": { + "description": "HTTP status code", + "type": "integer", + "minimum": 0 + }, + "error": { + "description": "Textual description of HTTP status code", + "type": "string" + }, + "message": { + "description": "Detailed information about the error.", + "type": "string" + }, + "loca": { + "description": "Unique message token that can be used for localization in a frontend application.", + "type": "string" + } + }, + "required": [ + "status", + "message", + "loca" + ], + "additionalProperties": false + } + + ++ Response 400 (application/json) + + Body + + { + "status":400, + "error":"Bad Request", + "message":"An username and a rank has to be given.", + "loca":"AUTH_SETRANK_MISSING_USERNAME_RANK" + } + + + Schema + + { + "type": "object", + "properties": { + "status": { + "description": "HTTP status code", + "type": "integer", + "minimum": 0 + }, + "error": { + "description": "Textual description of HTTP status code", + "type": "string" + }, + "message": { + "description": "Detailed information about the error.", + "type": "string" + }, + "loca": { + "description": "Unique message token that can be used for localization in a frontend application.", + "type": "string" + } + }, + "required": [ + "status", + "message", + "loca" + ], + "additionalProperties": false + } From b75f92705dd2e8a5a965106a7a06c058a6843c8f Mon Sep 17 00:00:00 2001 From: Namoshek Date: Wed, 7 Sep 2016 12:20:36 +0200 Subject: [PATCH 02/54] REST service: api-description update (added enums, detailed description for possible messages, missing API functions) --- .../snippet_sharing/api-description.apib | 1067 +++++++++++++++-- 1 file changed, 990 insertions(+), 77 deletions(-) diff --git a/doc/rest_api/snippet_sharing/api-description.apib b/doc/rest_api/snippet_sharing/api-description.apib index 8d94d504e6a..8968f3d847e 100644 --- a/doc/rest_api/snippet_sharing/api-description.apib +++ b/doc/rest_api/snippet_sharing/api-description.apib @@ -23,8 +23,13 @@ The API will try to authenticate the user by the submitted credentials. In case + Request (application/x-www-form-urlencoded) + Attributes - + username: the_username (string, required) - + password: aSecretPassword (string, required) + + username: `the_username` (string, required) + + The name of the user account which should be tried to authenticate. + + + password: `aSecretPassword` (string, required) + + The corresponding password for the supplied user account. + Schema @@ -48,12 +53,9 @@ The API will try to authenticate the user by the submitted credentials. In case } + Response 200 (application/json) - + Body - - { - "status": 200, - "token": "eyJ...Q2tY=" - } + + Attributes (object) + + status (number) - HTTP status code + + token (string) - The session token which can be used to authenticate against the server in further requests + Schema @@ -77,15 +79,57 @@ The API will try to authenticate the user by the submitted credentials. In case "additionalProperties": false } -+ Response 401 (application/json) - + Body - ++ Response 400 (application/json) + + Attributes (object) + + status (number) - HTTP status code + + error (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `AUTH_NEED_USERNAME_PASSWORD` in case either the `username` or the `password` field is missing in the request + + + Schema + { - "status": 401, - "error": "Unauthorized", - "message": "You have to supply an username and a password.", - "loca": "AUTH_NEED_USERNAME_PASSWORD" + "type": "object", + "properties": { + "status": { + "description": "HTTP status code", + "type": "integer", + "minimum": 0 + }, + "error": { + "description": "Textual description of HTTP status code", + "type": "string" + }, + "message": { + "description": "Detailed information about the error.", + "type": "string" + }, + "i18n": { + "description": "Unique message token that can be used for localization in a frontend application.", + "type": "string" + } + }, + "required": [ + "status", + "message", + "i18n" + ], + "additionalProperties": false } + ++ Response 401 (application/json) + + Attributes (object) + + status (number) - HTTP status code + + error (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `AUTH_UNKNOWN_USERNAME` if there is no user registered witht he given name + - `AUTH_INVALID_PASSWORD` if the given password does not match the password saved for the given account + Schema @@ -105,7 +149,48 @@ The API will try to authenticate the user by the submitted credentials. In case "description": "Detailed information about the error.", "type": "string" }, - "loca": { + "i18n": { + "description": "Unique message token that can be used for localization in a frontend application.", + "type": "string" + } + }, + "required": [ + "status", + "message", + "i18n" + ], + "additionalProperties": false + } + ++ Response 500 (application/json) + + Attributes (object) + + status (number) - HTTP status code + + error (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `AUTH_CREATE_JWT_ERROR` if the session token could not be created + + + Schema + + { + "type": "object", + "properties": { + "status": { + "description": "HTTP status code", + "type": "integer", + "minimum": 0 + }, + "error": { + "description": "Textual description of HTTP status code", + "type": "string" + }, + "message": { + "description": "Detailed information about the error.", + "type": "string" + }, + "i18n": { "description": "Unique message token that can be used for localization in a frontend application.", "type": "string" } @@ -113,7 +198,7 @@ The API will try to authenticate the user by the submitted credentials. In case "required": [ "status", "message", - "loca" + "i18n" ], "additionalProperties": false } @@ -124,13 +209,14 @@ The API will try to authenticate the user by the submitted credentials. In case Retrieves the currently authenticated users details. + Response 200 (application/json) - + Body - - { - "status": 200, - "username": "the_username", - "rank": 1 - } + + Attributes (object) + + status (number) - HTTP status code + + username (string) - The name of the currently authenticated user + + rank (enum[number]) - The rank of the currently authenticated user (higher means more permissions) + + Members + + `1` - Normal user + + `2` - Moderator + + `3` - Admin + Schema @@ -147,8 +233,8 @@ Retrieves the currently authenticated users details. "type": "string" }, "rank": { - "description": "The authenticated users rank", - "type": "integer" + "description": "The authenticated users rank. The higher the rank, the more permissions the user has. 1 is considered a normal user, 2 a moderator and 3 an admin.", + "enum": [1, 2, 3] } }, "required": [ @@ -160,14 +246,14 @@ Retrieves the currently authenticated users details. } + Response 401 (application/json) - + Body - - { - "status": 401, - "error": "Unauthorized", - "message": "You need to be authenticated to perform this action.", - "loca": "NEED_AUTHENTICATION" - } + + Attributes (object) + + status (number) - HTTP status code + + error (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `NEED_AUTHENTICATION` if no valid session token has been supplied or the user for whom the token has been created does not exist (anymore) + Schema @@ -187,7 +273,7 @@ Retrieves the currently authenticated users details. "description": "Detailed information about the error.", "type": "string" }, - "loca": { + "i18n": { "description": "Unique message token that can be used for localization in a frontend application.", "type": "string" } @@ -195,7 +281,7 @@ Retrieves the currently authenticated users details. "required": [ "status", "message", - "loca" + "i18n" ], "additionalProperties": false } @@ -207,21 +293,26 @@ This method can be used to register for the service. An user account will grant + Request Register via form (application/x-www-form-urlencoded) + Attributes - + username: the_username (string, required) + + username: `the_username` (string, required) The username must be between 3 and 20 signs long and may contain only letters a-z (lower- and upper-case), the numbers 0-9 and dots (.) as well as dashes (-). - + password: somePassword (string, required) - A non-empty password - + email: an@email.com (string, required) - A valid email address + + password: `somePassword` (string, required) + + The password must be at least 8 signs long and contain at least one lower-case and one upper-case letter. To harden security, the user is encouraged to use special characters as well. + + + email: `an@email.com` (string, required) + + The user has to supply a valid email address. + Response 200 (application/json) - + Body - - { - "status":200, - "message":"Your account has been created successfully!", - "loca":"AUTH_REGISTER_USER_CREATED_SUCCESSFULLY" - } + + Attributes (object) + + status (number) - HTTP status code + + message (string) - Detailed response information, normally success message + + i18n (string) - A unique token representing above message; can be used for internationalization in frontends + + A comprehensive list of possible messages: + - `AUTH_REGISTER_USER_CREATED_SUCCESSFULLY` if the account has been created successfully + Schema @@ -241,7 +332,7 @@ This method can be used to register for the service. An user account will grant "description": "Detailed information about the error.", "type": "string" }, - "loca": { + "i18n": { "description": "Unique message token that can be used for localization in a frontend application.", "type": "string" } @@ -249,20 +340,104 @@ This method can be used to register for the service. An user account will grant "required": [ "status", "message", - "loca" + "i18n" ], "additionalProperties": false } + Response 400 (application/json) - + Body + + Attributes (object) + + status (number) - HTTP status code + + error (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `AUTH_REGISTER_NEED_USERNAME_PASSWORD_EMAIL` if either no `username`, no `password` or no `email` has been supplied + - `AUTH_REGISTER_INVALID_USERNAME` if the supplied `username` does not match the given criteria (regex: [a-zA-Z0-9\-\.]{3,20}) + - `AUTH_REGISTER_INVALID_EMAIL` if the supplied `email` is not a valid email + + + Schema + + { + "type": "object", + "properties": { + "status": { + "description": "HTTP status code", + "type": "integer", + "minimum": 0 + }, + "error": { + "description": "Textual description of HTTP status code", + "type": "string" + }, + "message": { + "description": "Detailed information about the error.", + "type": "string" + }, + "i18n": { + "description": "Unique message token that can be used for localization in a frontend application.", + "type": "string" + } + }, + "required": [ + "status", + "message", + "i18n" + ], + "additionalProperties": false + } + ++ Response 422 (application/json) + + Attributes (object) + + status (number) - HTTP status code + + error (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `AUTH_REGISTER_USERNAME_DOES_ALREADY_EXIST` if the supplied `username` is already taken + + + Schema { - "status":400, - "error":"Bad Request", - "message":"You have to supply an username, a password and an email.", - "loca":"AUTH_REGISTER_NEED_USERNAME_PASSWORD_EMAIL" + "type": "object", + "properties": { + "status": { + "description": "HTTP status code", + "type": "integer", + "minimum": 0 + }, + "error": { + "description": "Textual description of HTTP status code", + "type": "string" + }, + "message": { + "description": "Detailed information about the error.", + "type": "string" + }, + "i18n": { + "description": "Unique message token that can be used for localization in a frontend application.", + "type": "string" + } + }, + "required": [ + "status", + "message", + "i18n" + ], + "additionalProperties": false } + ++ Response 500 (application/json) + + Attributes (object) + + status (number) - HTTP status code + + error (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `AUTH_REGISTER_UNKNOWN_ERROR` if the account could not be created due to an internal server error + Schema @@ -282,7 +457,7 @@ This method can be used to register for the service. An user account will grant "description": "Detailed information about the error.", "type": "string" }, - "loca": { + "i18n": { "description": "Unique message token that can be used for localization in a frontend application.", "type": "string" } @@ -290,7 +465,7 @@ This method can be used to register for the service. An user account will grant "required": [ "status", "message", - "loca" + "i18n" ], "additionalProperties": false } @@ -298,12 +473,22 @@ This method can be used to register for the service. An user account will grant ## Set user rank [POST /setrank] -This method can be used to set the rank of an user. Only users with a rank high enough have the privilegue to set the rank of users. +This method can be used to set the rank of an user. The higher the rank, the more permissions an user has. Rank 1 is considered a normal user, 2 a moderator and 3 an admin. Only users with the highest rank (3) have the privilegue to set the rank of other users. + Request Set rank via form (application/x-www-form-urlencoded) + Attributes - + username: the_username (string, required) - + rank: 3 (number, required) + + username: `the_username` (string, required) + + The name of the user whos rank should be altered. + + + rank: `3` (enum[number], required) + + The new rank to apply to the submitted user. + + + Members + + `1` - Normal user + + `2` - Moderator + + `3` - Admin + Schema @@ -316,8 +501,7 @@ This method can be used to set the rank of an user. Only users with a rank high }, "rank": { "description": "The new rank to apply to the user", - "type": "integer", - "minimum": 0 + "enum": [1, 2, 3] } }, "required": [ @@ -328,13 +512,13 @@ This method can be used to set the rank of an user. Only users with a rank high } + Response 200 (application/json) - + Body - - { - "status": 200, - "message": "The rank has been set successfully.", - "loca": "USER_SET_RANK_SUCCESSFULLY" - } + + Attributes (object) + + status (number) - HTTP status code + + message (string) - Detailed response information, normally success message + + i18n (string) - A unique token representing above message; can be used for internationalization in frontends + + A comprehensive list of possible messages: + - `USER_SET_RANK_SUCCESSFULLY` if the rank of the supplied user has been changed successfully + Schema @@ -354,7 +538,7 @@ This method can be used to set the rank of an user. Only users with a rank high "description": "Detailed information about the error.", "type": "string" }, - "loca": { + "i18n": { "description": "Unique message token that can be used for localization in a frontend application.", "type": "string" } @@ -362,22 +546,168 @@ This method can be used to set the rank of an user. Only users with a rank high "required": [ "status", "message", - "loca" + "i18n" ], "additionalProperties": false } + Response 400 (application/json) - + Body + + Attributes (object) + + status (number) - HTTP status code + + error (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `AUTH_SETRANK_MISSING_USERNAME_RANK` if either the `username` or the `rank` has not been supplied + - `AUTH_SETRANK_NONNUMERIC_RANK` if the supplied `rank` is not of numeric type + - `AUTH_SETRANK_INVALID_RANK` if the supplied `rank` is out of the allowed range (1-3) + - `USER_DOES_NOT_EXIST` if no account with the supplied `username` exists + + + Schema { - "status":400, - "error":"Bad Request", - "message":"An username and a rank has to be given.", - "loca":"AUTH_SETRANK_MISSING_USERNAME_RANK" + "type": "object", + "properties": { + "status": { + "description": "HTTP status code", + "type": "integer", + "minimum": 0 + }, + "error": { + "description": "Textual description of HTTP status code", + "type": "string" + }, + "message": { + "description": "Detailed information about the error.", + "type": "string" + }, + "i18n": { + "description": "Unique message token that can be used for localization in a frontend application.", + "type": "string" + } + }, + "required": [ + "status", + "message", + "i18n" + ], + "additionalProperties": false } - + ++ Response 401 (application/json) + + Attributes (object) + + status (number) - HTTP status code + + error (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `NEED_AUTHENTICATION` if no valid session token has been supplied or the user for whom the token has been created does not exist (anymore) + - `USER_INSUFFICIENT_RIGHTS_TO_SET_RANK` if the currently authenticated user has insufficient permissions (due to his rank) to perform this action + + + Schema + + { + "type": "object", + "properties": { + "status": { + "description": "HTTP status code", + "type": "integer", + "minimum": 0 + }, + "error": { + "description": "Textual description of HTTP status code", + "type": "string" + }, + "message": { + "description": "Detailed information about the error.", + "type": "string" + }, + "i18n": { + "description": "Unique message token that can be used for localization in a frontend application.", + "type": "string" + } + }, + "required": [ + "status", + "message", + "i18n" + ], + "additionalProperties": false + } + + + +# Database endpoint [/database{?offset}{?rows}{?sort}{?search}{?raw}] + +## List database entries [GET /database/{scope}/{organization}/{application}/{appscope}{?offset}{?rows}{?sort}{?search}] + +Returns a list of database entries. The result can be adjusted by additional, but optional parameters. + ++ Parameters + + scope (string, optional) - Only search within a given `scope` for entries + + organization (string, optional) - Only search within a given `organization` for entries + + application (string, optional) - Only search within a given `application` for entries + + appscope (string, optional) - Only search within a given `scope` of an `application` for entries + + offset (number, optional) - How many entries to skip for the output, can be used for pagination. + + Default: `0` + + rows (number, optional) - How many entries will be added to the output at max. + + Default: `200` + + sort (enum[string], optional) - How to sort the entries for the output. + + Default: `asc` + + Members + + `asc` + + `desc` + + search (string, optional) - Only entries containing the search string in either their path, title, description, author or tags will be added to the output. + ++ Response 200 (application/json) + + Attributes (Entry List) + + +## Get details for entry [GET /database/{scope}/{organization}/{application}/{appscope}/{slug}{?raw}] + +Returns detailed information about the entry with the specified key (path). If the optional parameter `raw` is supplied, a raw configuration is returned instead of the normal response. + ++ Parameters + + scope (string, required) - The `scope` for the configuration snippet of the entry + + organization (string, required) - The `organization` who built the `application` for which the configuration of the entry is meant + + application (string, required) - The `application` to which the configuration of the entry belongs to + + appscope (string, required) - The `application` specific `scope` to which the configuration of the entry belongs to + + slug (string, required) - The unique identifier of the requested entry + + raw (string, optional) - If this parameter is supplied, the API will attempt to return the requested configuration snippet in the given `raw` format + ++ Response 200 (application/json) + + Attributes (object) + + status (number) - HTTP status code + + data (object) - The actual details about the entry + + key (object) - The key and its separate parts + + full (string) - The full key (path) of the entry + + scope (string) - The scope of the configuration snippet + + organization (string) - The organization of the application to which the snippet belongs to + + application (string) - The application to which the snippet belongs to + + appscope (string) - The application internal scope for the configuration snippet + + slug (string) - The unique identification slug of the entry + + meta (object) - Additional information about the entry + + title (string) - The descriptive title of the entry + + description (string) - The extended description of the entry + + author (string) - The name of the creator of the entry + + created_at (number) - A timestamp of the creation date of the entry + + value (array[object]) + + format (string) - A configuration format, e.g. **ini** + + value (string) - The configuration snippet in above mentioned format + ++ Response 404 (application/json) + + Attributes (object) + + status (number) - HTTP status code + + error (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `ENTRY_DOES_NOT_EXIST` if an entry with the given key (path) does not exist in the database + + Schema { @@ -396,7 +726,7 @@ This method can be used to set the rank of an user. Only users with a rank high "description": "Detailed information about the error.", "type": "string" }, - "loca": { + "i18n": { "description": "Unique message token that can be used for localization in a frontend application.", "type": "string" } @@ -404,7 +734,590 @@ This method can be used to set the rank of an user. Only users with a rank high "required": [ "status", "message", - "loca" + "i18n" ], "additionalProperties": false } + + +## Create database entry [POST] + +Can be used to create a new entry in the database. An entry consists of a unique key (path) that is built from several individual inputs, a title, description and a configuration snippet in any supported format. + ++ Request (application/x-www-form-urlencoded) + + Attributes + + scope: `sw` (string, required) + + The scope of the new configuration snippet. Common scopes are `sw` for software and `env` for environment for example. + + + organization: `org.apache` (string, required) + + The organization which built the software for which the configuration is meant. + + + application: `hive` (string, required) + + The application for which the configuration is meant. + + + appscope: `database` (string, required) + + Often different parts of an application have different configurations. Here the application specific scope can be defined. + + + slug: `sample-snippet-for-devs` (string, required) + + A unique slug that identifies the entry and configuration snippet further. + + + title: `Sample snippet for developers` (string, required) + + A title for the entry that ideally explains already what the snippet is about. + + + description: `This is a sample conf snippet for Apaches Hive database module.` (string, required) + + An extended description for the entry that explains in detail what the snippet is about. It can also contain instructions on how to use the snippet. + + + tags: `dev`, `developer`, `db-dev` (array[string], optional) + + A list of tags that shall be added to the entry. Tags may be used for search, so they ideally add additional information that is not already available by the other inputs. + + + configuration: `sampleKey = sampleValue` (string, required) + + The configuration for which a new database entry should be created. It can be of any supported format, in this example **ini** is used. + + + Schema + + { + "type": "object", + "properties": { + "scope": { + "description": "The scope of the new configuration snippet", + "type": "string" + }, + "organization": { + "description": "The organization which built the software for which the configuration is meant", + "type": "string" + }, + "application": { + "description": "The application for which the configuration is meant", + "type": "string" + }, + "appscope": { + "description": "The scope within the application for which the configuration is meant", + "type": "string" + }, + "slug": { + "description": "A unique slug that identifies the entry and configuration snippet further", + "type": "string" + }, + "title": { + "description": "A title for the entry that tells what the snippet is about", + "type": "string" + }, + "description": { + "description": "An extended description for the entry that explains in detail what the snippet is about", + "type": "string" + }, + "tags": { + "description": "A list of tags that shall be added to the entry", + "type": "array", + "items": { + "type": "string" + }, + "uniqueItems": true + }, + "configuration": { + "description": "The configuration snippet in any supported format", + "type": "string" + } + }, + "required": [ + "scope", + "organization", + "application", + "appscope", + "slug", + "title", + "description", + "configuration" + ], + "additionalProperties": false + } + ++ Response 200 (application/json) + + Attributes (object) + + status (number) - HTTP status code + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible messages: + - `ENTRY_CREATED_SUCCESSFULLY` if the entry has been added successfully to the database + + + Schema + + { + "type": "object", + "properties": { + "status": { + "description": "HTTP status code", + "type": "integer", + "minimum": 0 + }, + "error": { + "description": "Textual description of HTTP status code", + "type": "string" + }, + "message": { + "description": "Detailed information about the error.", + "type": "string" + }, + "i18n": { + "description": "Unique message token that can be used for localization in a frontend application.", + "type": "string" + } + }, + "required": [ + "status", + "message", + "i18n" + ], + "additionalProperties": false + } + ++ Response 400 (application/json) + + Attributes (object) + + status (number) - HTTP status code + + error (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `ENTRY_MISSING_KEY_PARTS` if one of the five key parts (`scope`, `organization`, `application`, `appscope` and `slug`) is missing + - `ENTRY_MISSING_BASIC_VALUES` if one of the descriptive inputs (`title`, `description`, `configuration`) is missing + - `ENTRY_INVALID_KEY_PARTS` if one of the five key parts (`scope`, `organization`, `application`, `appscope` and `slug`) is malformed (regex: [a-zA-Z0-9\.\-]+). + - `ENTRY_INVALID_CONFIGURATION` if the submitted configuration snippet has an unsupported format. + + + Schema + + { + "type": "object", + "properties": { + "status": { + "description": "HTTP status code", + "type": "integer", + "minimum": 0 + }, + "error": { + "description": "Textual description of HTTP status code", + "type": "string" + }, + "message": { + "description": "Detailed information about the error.", + "type": "string" + }, + "i18n": { + "description": "Unique message token that can be used for localization in a frontend application.", + "type": "string" + } + }, + "required": [ + "status", + "message", + "i18n" + ], + "additionalProperties": false + } + ++ Response 401 (application/json) + + Attributes (object) + + status (number) - HTTP status code + + error (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `NEED_AUTHENTICATION` if no valid session token has been supplied or the user for whom the token has been created does not exist (anymore) + + + Schema + + { + "type": "object", + "properties": { + "status": { + "description": "HTTP status code", + "type": "integer", + "minimum": 0 + }, + "error": { + "description": "Textual description of HTTP status code", + "type": "string" + }, + "message": { + "description": "Detailed information about the error.", + "type": "string" + }, + "i18n": { + "description": "Unique message token that can be used for localization in a frontend application.", + "type": "string" + } + }, + "required": [ + "status", + "message", + "i18n" + ], + "additionalProperties": false + } + ++ Response 422 (application/json) + + Attributes (object) + + status (number) - HTTP status code + + error (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `ENTRY_DOES_ALREADY_EXIST` if an entry with the supplied key parts (`scope`, `organization`, `application`, `appscope` and `slug`) does already exist. + + + Schema + + { + "type": "object", + "properties": { + "status": { + "description": "HTTP status code", + "type": "integer", + "minimum": 0 + }, + "error": { + "description": "Textual description of HTTP status code", + "type": "string" + }, + "message": { + "description": "Detailed information about the error.", + "type": "string" + }, + "i18n": { + "description": "Unique message token that can be used for localization in a frontend application.", + "type": "string" + } + }, + "required": [ + "status", + "message", + "i18n" + ], + "additionalProperties": false + } + + +## Update an existing entry [PUT /database/{scope}/{organization}/{application}/{appscope}/{slug}] + +Updates the entry with the specified key (path). All fields will be overridden with the supplied data. If no or empty data is supplied, it will be used instead (especially important for `tags`). + ++ Parameters + + scope (string, required) - The `scope` for the configuration snippet of the entry + + organization (string, required) - The `organization` who built the `application` for which the configuration of the entry is meant + + application (string, required) - The `application` to which the configuration of the entry belongs to + + appscope (string, required) - The `application` specific `scope` to which the configuration of the entry belongs to + + slug (string, required) - The unique identifier of the requested entry + ++ Request (application/x-www-form-urlencoded) + + Attributes + + title: `Sample snippet for developers` (string, required) + + A title for the entry that ideally explains already what the snippet is about. + + + description: `This is a sample conf snippet for Apaches Hive database module.` (string, required) + + An extended description for the entry that explains in detail what the snippet is about. It can also contain instructions on how to use the snippet. + + + tags: `dev`, `developer`, `db-dev` (array[string], optional) + + A list of tags that shall be added to the entry. Tags may be used for search, so they ideally add additional information that is not already available by the other inputs. + + + configuration: `sampleKey = sampleValue` (string, required) + + The configuration for which a new database entry should be created. It can be of any supported format, in this example **ini** is used. + + + Schema + + { + "type": "object", + "properties": { + "title": { + "description": "A title for the entry that tells what the snippet is about", + "type": "string" + }, + "description": { + "description": "An extended description for the entry that explains in detail what the snippet is about", + "type": "string" + }, + "tags": { + "description": "A list of tags that shall be added to the entry", + "type": "array", + "items": { + "type": "string" + }, + "uniqueItems": true + }, + "configuration": { + "description": "The configuration snippet in any supported format", + "type": "string" + } + }, + "required": [ + "title", + "description", + "configuration" + ], + "additionalProperties": false + } + ++ Response 400 (application/json) + + Attributes (object) + + status (number) - HTTP status code + + error (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `ENTRY_MISSING_BASIC_VALUES` if one of the descriptive inputs (`title`, `description`, `configuration`) is missing + - `ENTRY_INVALID_CONFIGURATION` if the submitted configuration snippet has an unsupported format. + + + Schema + + { + "type": "object", + "properties": { + "status": { + "description": "HTTP status code", + "type": "integer", + "minimum": 0 + }, + "error": { + "description": "Textual description of HTTP status code", + "type": "string" + }, + "message": { + "description": "Detailed information about the error.", + "type": "string" + }, + "i18n": { + "description": "Unique message token that can be used for localization in a frontend application.", + "type": "string" + } + }, + "required": [ + "status", + "message", + "i18n" + ], + "additionalProperties": false + } + ++ Response 401 (application/json) + + Attributes (object) + + status (number) - HTTP status code + + error (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `NEED_AUTHENTICATION` if no valid session token has been supplied or the user for whom the token has been created does not exist (anymore) + - `ENTRY_INSUFFICIENT_RIGHTS_TO_MANIPULATE` if the currently authenticated user has insufficient rights to update the entry (i.e. normal user, but not owner) + + + Schema + + { + "type": "object", + "properties": { + "status": { + "description": "HTTP status code", + "type": "integer", + "minimum": 0 + }, + "error": { + "description": "Textual description of HTTP status code", + "type": "string" + }, + "message": { + "description": "Detailed information about the error.", + "type": "string" + }, + "i18n": { + "description": "Unique message token that can be used for localization in a frontend application.", + "type": "string" + } + }, + "required": [ + "status", + "message", + "i18n" + ], + "additionalProperties": false + } + ++ Response 404 (application/json) + + Attributes (object) + + status (number) - HTTP status code + + error (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `ENTRY_TO_UPDATE_DOES_NOT_EXIST` if the entry that specified by the URI does not exist in the database + + + Schema + + { + "type": "object", + "properties": { + "status": { + "description": "HTTP status code", + "type": "integer", + "minimum": 0 + }, + "error": { + "description": "Textual description of HTTP status code", + "type": "string" + }, + "message": { + "description": "Detailed information about the error.", + "type": "string" + }, + "i18n": { + "description": "Unique message token that can be used for localization in a frontend application.", + "type": "string" + } + }, + "required": [ + "status", + "message", + "i18n" + ], + "additionalProperties": false + } + + +## Delete an entry [DELETE /database/{scope}/{organization}/{application}/{appscope}/{slug}] + +Deletes an entry from the database. This operation requires moderator permissions (rank 2). + ++ Parameters + + scope (string, required) - The `scope` for the configuration snippet of the entry + + organization (string, required) - The `organization` who built the `application` for which the configuration of the entry is meant + + application (string, required) - The `application` to which the configuration of the entry belongs to + + appscope (string, required) - The `application` specific `scope` to which the configuration of the entry belongs to + + slug (string, required) - The unique identifier of the requested entry + ++ Response 200 (application/json) + + Attributes (object) + + status (number) - HTTP status code + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible messages: + - `ENTRY_DELETED_SUCCESSFULLY` if the entry has been deleted successfully from the database + ++ Response 401 (application/json) + + Attributes (object) + + status (number) - HTTP status code + + error (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `NEED_AUTHENTICATION` if no valid session token has been supplied or the user for whom the token has been created does not exist (anymore) + - `ENTRY_INSUFFICIENT_RIGHTS_TO_DELETE` if the currently authenticated user has insufficient permissions to delete the entry + + + Schema + + { + "type": "object", + "properties": { + "status": { + "description": "HTTP status code", + "type": "integer", + "minimum": 0 + }, + "error": { + "description": "Textual description of HTTP status code", + "type": "string" + }, + "message": { + "description": "Detailed information about the error.", + "type": "string" + }, + "i18n": { + "description": "Unique message token that can be used for localization in a frontend application.", + "type": "string" + } + }, + "required": [ + "status", + "message", + "i18n" + ], + "additionalProperties": false + } + ++ Response 404 (application/json) + + Attributes (object) + + status (number) - HTTP status code + + error (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `ENTRY_TO_DELETE_DOES_NOT_EXIST if the entry that specified by the URI does not exist in the database + + + Schema + + { + "type": "object", + "properties": { + "status": { + "description": "HTTP status code", + "type": "integer", + "minimum": 0 + }, + "error": { + "description": "Textual description of HTTP status code", + "type": "string" + }, + "message": { + "description": "Detailed information about the error.", + "type": "string" + }, + "i18n": { + "description": "Unique message token that can be used for localization in a frontend application.", + "type": "string" + } + }, + "required": [ + "status", + "message", + "i18n" + ], + "additionalProperties": false + } + + + +# Data Structures + +## Entry List (object) + ++ status (number) - HTTP status code ++ elements (number) - How many entries the response list contains ++ entries (array[Entry Preview]) - A list of previews for entries ++ offset (number) - How many entries have been skipped for the output; this information can be used for pagination ++ remaining (number) - How many entries have not been displayed yet; when adding this value to the offset (and not exceeding the row limit), all entries should have been displayed once ++ formats (array[string]) - A list of available (enabled) configuration formats; formats in this list can be selected for export + + +## Entry Preview (object) + ++ key (string) - Storage path of the entry and also the unique identifier ++ title (string) - How the entry/snippet has been named by the creator ++ description (string) - A description of the entry ++ author (string) - The username of the creator of the entry ++ created_at (number) - A timestamp of when the entry has been created \ No newline at end of file From dad8f6035e9d7196366bd93df640a6d93def9fcd Mon Sep 17 00:00:00 2001 From: Namoshek Date: Wed, 7 Sep 2016 17:43:51 +0200 Subject: [PATCH 03/54] REST service: api-description updated (removed normal scope, renamed appscope to scope, fixed description of DELETE entry method) --- .../snippet_sharing/api-description.apib | 46 +++++++------------ 1 file changed, 16 insertions(+), 30 deletions(-) diff --git a/doc/rest_api/snippet_sharing/api-description.apib b/doc/rest_api/snippet_sharing/api-description.apib index 8968f3d847e..e1290d37247 100644 --- a/doc/rest_api/snippet_sharing/api-description.apib +++ b/doc/rest_api/snippet_sharing/api-description.apib @@ -642,15 +642,14 @@ This method can be used to set the rank of an user. The higher the rank, the mor # Database endpoint [/database{?offset}{?rows}{?sort}{?search}{?raw}] -## List database entries [GET /database/{scope}/{organization}/{application}/{appscope}{?offset}{?rows}{?sort}{?search}] +## List database entries [GET /database/{organization}/{application}/{scope}{?offset}{?rows}{?sort}{?search}] Returns a list of database entries. The result can be adjusted by additional, but optional parameters. + Parameters - + scope (string, optional) - Only search within a given `scope` for entries + organization (string, optional) - Only search within a given `organization` for entries + application (string, optional) - Only search within a given `application` for entries - + appscope (string, optional) - Only search within a given `scope` of an `application` for entries + + scope (string, optional) - Only search within a given `scope` of an `application` for entries + offset (number, optional) - How many entries to skip for the output, can be used for pagination. + Default: `0` + rows (number, optional) - How many entries will be added to the output at max. @@ -666,15 +665,14 @@ Returns a list of database entries. The result can be adjusted by additional, bu + Attributes (Entry List) -## Get details for entry [GET /database/{scope}/{organization}/{application}/{appscope}/{slug}{?raw}] +## Get details for entry [GET /database/{organization}/{application}/{scope}/{slug}{?raw}] Returns detailed information about the entry with the specified key (path). If the optional parameter `raw` is supplied, a raw configuration is returned instead of the normal response. + Parameters - + scope (string, required) - The `scope` for the configuration snippet of the entry + organization (string, required) - The `organization` who built the `application` for which the configuration of the entry is meant + application (string, required) - The `application` to which the configuration of the entry belongs to - + appscope (string, required) - The `application` specific `scope` to which the configuration of the entry belongs to + + scope (string, required) - The `application` specific `scope` to which the configuration of the entry belongs to + slug (string, required) - The unique identifier of the requested entry + raw (string, optional) - If this parameter is supplied, the API will attempt to return the requested configuration snippet in the given `raw` format @@ -684,10 +682,9 @@ Returns detailed information about the entry with the specified key (path). If t + data (object) - The actual details about the entry + key (object) - The key and its separate parts + full (string) - The full key (path) of the entry - + scope (string) - The scope of the configuration snippet + organization (string) - The organization of the application to which the snippet belongs to + application (string) - The application to which the snippet belongs to - + appscope (string) - The application internal scope for the configuration snippet + + scope (string) - The application internal scope for the configuration snippet + slug (string) - The unique identification slug of the entry + meta (object) - Additional information about the entry + title (string) - The descriptive title of the entry @@ -746,10 +743,6 @@ Can be used to create a new entry in the database. An entry consists of a unique + Request (application/x-www-form-urlencoded) + Attributes - + scope: `sw` (string, required) - - The scope of the new configuration snippet. Common scopes are `sw` for software and `env` for environment for example. - + organization: `org.apache` (string, required) The organization which built the software for which the configuration is meant. @@ -758,7 +751,7 @@ Can be used to create a new entry in the database. An entry consists of a unique The application for which the configuration is meant. - + appscope: `database` (string, required) + + scope: `database` (string, required) Often different parts of an application have different configurations. Here the application specific scope can be defined. @@ -787,10 +780,6 @@ Can be used to create a new entry in the database. An entry consists of a unique { "type": "object", "properties": { - "scope": { - "description": "The scope of the new configuration snippet", - "type": "string" - }, "organization": { "description": "The organization which built the software for which the configuration is meant", "type": "string" @@ -799,7 +788,7 @@ Can be used to create a new entry in the database. An entry consists of a unique "description": "The application for which the configuration is meant", "type": "string" }, - "appscope": { + "scope": { "description": "The scope within the application for which the configuration is meant", "type": "string" }, @@ -829,10 +818,9 @@ Can be used to create a new entry in the database. An entry consists of a unique } }, "required": [ - "scope", "organization", "application", - "appscope", + "scope", "slug", "title", "description", @@ -889,9 +877,9 @@ Can be used to create a new entry in the database. An entry consists of a unique + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: - - `ENTRY_MISSING_KEY_PARTS` if one of the five key parts (`scope`, `organization`, `application`, `appscope` and `slug`) is missing + - `ENTRY_MISSING_KEY_PARTS` if one of the four key parts (`organization`, `application`, `scope` and `slug`) is missing - `ENTRY_MISSING_BASIC_VALUES` if one of the descriptive inputs (`title`, `description`, `configuration`) is missing - - `ENTRY_INVALID_KEY_PARTS` if one of the five key parts (`scope`, `organization`, `application`, `appscope` and `slug`) is malformed (regex: [a-zA-Z0-9\.\-]+). + - `ENTRY_INVALID_KEY_PARTS` if one of the four key parts (`organization`, `application`, `scope` and `slug`) is malformed (regex: [a-zA-Z0-9\.\-]+). - `ENTRY_INVALID_CONFIGURATION` if the submitted configuration snippet has an unsupported format. + Schema @@ -974,7 +962,7 @@ Can be used to create a new entry in the database. An entry consists of a unique + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: - - `ENTRY_DOES_ALREADY_EXIST` if an entry with the supplied key parts (`scope`, `organization`, `application`, `appscope` and `slug`) does already exist. + - `ENTRY_DOES_ALREADY_EXIST` if an entry with the supplied four key parts (`organization`, `application`, `scope` and `slug`) does already exist. + Schema @@ -1008,15 +996,14 @@ Can be used to create a new entry in the database. An entry consists of a unique } -## Update an existing entry [PUT /database/{scope}/{organization}/{application}/{appscope}/{slug}] +## Update an existing entry [PUT /database/{organization}/{application}/{scope}/{slug}] Updates the entry with the specified key (path). All fields will be overridden with the supplied data. If no or empty data is supplied, it will be used instead (especially important for `tags`). + Parameters - + scope (string, required) - The `scope` for the configuration snippet of the entry + organization (string, required) - The `organization` who built the `application` for which the configuration of the entry is meant + application (string, required) - The `application` to which the configuration of the entry belongs to - + appscope (string, required) - The `application` specific `scope` to which the configuration of the entry belongs to + + scope (string, required) - The `application` specific `scope` to which the configuration of the entry belongs to + slug (string, required) - The unique identifier of the requested entry + Request (application/x-www-form-urlencoded) @@ -1197,15 +1184,14 @@ Updates the entry with the specified key (path). All fields will be overridden w } -## Delete an entry [DELETE /database/{scope}/{organization}/{application}/{appscope}/{slug}] +## Delete an entry [DELETE /database/{organization}/{application}/{scope}/{slug}] -Deletes an entry from the database. This operation requires moderator permissions (rank 2). +Deletes an entry from the database. This operation can only be executed by the owner of an entry as well as moderators (rank 2) or higher. + Parameters - + scope (string, required) - The `scope` for the configuration snippet of the entry + organization (string, required) - The `organization` who built the `application` for which the configuration of the entry is meant + application (string, required) - The `application` to which the configuration of the entry belongs to - + appscope (string, required) - The `application` specific `scope` to which the configuration of the entry belongs to + + scope (string, required) - The `application` specific `scope` to which the configuration of the entry belongs to + slug (string, required) - The unique identifier of the requested entry + Response 200 (application/json) From 6c47830b4ac152a77009281d49ea1f0abf30887c Mon Sep 17 00:00:00 2001 From: Namoshek Date: Wed, 7 Sep 2016 17:51:19 +0200 Subject: [PATCH 04/54] REST service: api-description updated (changed description of some operations) --- doc/rest_api/snippet_sharing/api-description.apib | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/doc/rest_api/snippet_sharing/api-description.apib b/doc/rest_api/snippet_sharing/api-description.apib index e1290d37247..ddd1fbfa9f9 100644 --- a/doc/rest_api/snippet_sharing/api-description.apib +++ b/doc/rest_api/snippet_sharing/api-description.apib @@ -289,7 +289,7 @@ Retrieves the currently authenticated users details. ## Register [POST /register] -This method can be used to register for the service. An user account will grant access to more functionality. +This method can be used to register for the service. An user account will grant access to more functions. + Request Register via form (application/x-www-form-urlencoded) + Attributes @@ -473,7 +473,9 @@ This method can be used to register for the service. An user account will grant ## Set user rank [POST /setrank] -This method can be used to set the rank of an user. The higher the rank, the more permissions an user has. Rank 1 is considered a normal user, 2 a moderator and 3 an admin. Only users with the highest rank (3) have the privilegue to set the rank of other users. +This method can be used to change the rank of an user. The higher the rank, the more permissions an user has. Rank 1 is considered a normal user, 2 a moderator and 3 an admin. + +This operation can only be executed by admins (rank 3). + Request Set rank via form (application/x-www-form-urlencoded) + Attributes @@ -998,7 +1000,9 @@ Can be used to create a new entry in the database. An entry consists of a unique ## Update an existing entry [PUT /database/{organization}/{application}/{scope}/{slug}] -Updates the entry with the specified key (path). All fields will be overridden with the supplied data. If no or empty data is supplied, it will be used instead (especially important for `tags`). +Updates the entry with the specified key (path). All fields will be overridden with the supplied data. If no or empty data is supplied, it will also override the old one (especially important for `tags`). + +This operation can only be executed by the owner of an entry as well as moderators (rank 2) or higher. + Parameters + organization (string, required) - The `organization` who built the `application` for which the configuration of the entry is meant @@ -1186,7 +1190,9 @@ Updates the entry with the specified key (path). All fields will be overridden w ## Delete an entry [DELETE /database/{organization}/{application}/{scope}/{slug}] -Deletes an entry from the database. This operation can only be executed by the owner of an entry as well as moderators (rank 2) or higher. +Deletes an entry from the database. + +This operation can only be executed by the owner of an entry as well as moderators (rank 2) or higher. + Parameters + organization (string, required) - The `organization` who built the `application` for which the configuration of the entry is meant From e8de3fd8d9c0764a62b058ff8361fca642aca30e Mon Sep 17 00:00:00 2001 From: Namoshek Date: Thu, 8 Sep 2016 09:27:40 +0200 Subject: [PATCH 05/54] REST service: api-description updated (switch request format to application/json) --- .../snippet_sharing/api-description.apib | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/doc/rest_api/snippet_sharing/api-description.apib b/doc/rest_api/snippet_sharing/api-description.apib index ddd1fbfa9f9..ad9f0057ad5 100644 --- a/doc/rest_api/snippet_sharing/api-description.apib +++ b/doc/rest_api/snippet_sharing/api-description.apib @@ -21,8 +21,8 @@ Returns an overview of available API methods with required parameters and a desc The API will try to authenticate the user by the submitted credentials. In case of success a session token (JWT) will be returned, which can be used for further requests to the API. -+ Request (application/x-www-form-urlencoded) - + Attributes ++ Request (application/json) + + Attributes (object) + username: `the_username` (string, required) The name of the user account which should be tried to authenticate. @@ -291,8 +291,8 @@ Retrieves the currently authenticated users details. This method can be used to register for the service. An user account will grant access to more functions. -+ Request Register via form (application/x-www-form-urlencoded) - + Attributes ++ Request (application/json) + + Attributes (object) + username: `the_username` (string, required) The username must be between 3 and 20 signs long and may contain only letters a-z (lower- and upper-case), the numbers 0-9 and dots (.) as well as dashes (-). @@ -477,8 +477,8 @@ This method can be used to change the rank of an user. The higher the rank, the This operation can only be executed by admins (rank 3). -+ Request Set rank via form (application/x-www-form-urlencoded) - + Attributes ++ Request (application/json) + + Attributes (object) + username: `the_username` (string, required) The name of the user whos rank should be altered. @@ -743,8 +743,8 @@ Returns detailed information about the entry with the specified key (path). If t Can be used to create a new entry in the database. An entry consists of a unique key (path) that is built from several individual inputs, a title, description and a configuration snippet in any supported format. -+ Request (application/x-www-form-urlencoded) - + Attributes ++ Request (application/json) + + Attributes (object) + organization: `org.apache` (string, required) The organization which built the software for which the configuration is meant. @@ -1010,8 +1010,8 @@ This operation can only be executed by the owner of an entry as well as moderato + scope (string, required) - The `application` specific `scope` to which the configuration of the entry belongs to + slug (string, required) - The unique identifier of the requested entry -+ Request (application/x-www-form-urlencoded) - + Attributes ++ Request (application/json) + + Attributes (object) + title: `Sample snippet for developers` (string, required) A title for the entry that ideally explains already what the snippet is about. From 9f83497dc94c5d4359b5d9cada1a5173dec1e058 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Thu, 8 Sep 2016 11:26:14 +0200 Subject: [PATCH 06/54] REST service: api-description updated (added regex for inputs, added more error codes, added new search parameters) --- .../snippet_sharing/api-description.apib | 119 +++++++++++++----- 1 file changed, 89 insertions(+), 30 deletions(-) diff --git a/doc/rest_api/snippet_sharing/api-description.apib b/doc/rest_api/snippet_sharing/api-description.apib index ad9f0057ad5..0fc26d0f0b0 100644 --- a/doc/rest_api/snippet_sharing/api-description.apib +++ b/doc/rest_api/snippet_sharing/api-description.apib @@ -23,11 +23,12 @@ The API will try to authenticate the user by the submitted credentials. In case + Request (application/json) + Attributes (object) - + username: `the_username` (string, required) + + username: `the-username` (string, required) The name of the user account which should be tried to authenticate. + Regex: ^[a-zA-Z0-9\-\.]{3,20}$ - + password: `aSecretPassword` (string, required) + + password: `a5ecretP4ssword` (string, required) The corresponding password for the supplied user account. @@ -87,7 +88,8 @@ The API will try to authenticate the user by the submitted credentials. In case + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: - - `AUTH_NEED_USERNAME_PASSWORD` in case either the `username` or the `password` field is missing in the request + - `AUTH_MISSING_USERNAME` if no input for `username` was submitted + - `AUTH_MISSING_PASSWORD` if no input for `password` was submitted + Schema @@ -170,7 +172,7 @@ The API will try to authenticate the user by the submitted credentials. In case + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: - - `AUTH_CREATE_JWT_ERROR` if the session token could not be created + - `AUTH_CREATE_TOKEN_ERROR` if the session token could not be created + Schema @@ -296,10 +298,13 @@ This method can be used to register for the service. An user account will grant + username: `the_username` (string, required) The username must be between 3 and 20 signs long and may contain only letters a-z (lower- and upper-case), the numbers 0-9 and dots (.) as well as dashes (-). + Regex: ^[a-zA-Z0-9\-\.]{3,20}$ + password: `somePassword` (string, required) - The password must be at least 8 signs long and contain at least one lower-case and one upper-case letter. To harden security, the user is encouraged to use special characters as well. + The password must be at least 8 signs long and contain at least one lower-case letter, one upper-case letter and one digit. + To harden security, the user is encouraged to use special characters as well. + Regex: ^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[a-zA-Z\d]{8,}$ + email: `an@email.com` (string, required) @@ -312,7 +317,7 @@ This method can be used to register for the service. An user account will grant + i18n (string) - A unique token representing above message; can be used for internationalization in frontends A comprehensive list of possible messages: - - `AUTH_REGISTER_USER_CREATED_SUCCESSFULLY` if the account has been created successfully + - `REGISTER_USER_CREATED_SUCCESSFULLY` if the account has been created successfully + Schema @@ -353,9 +358,12 @@ This method can be used to register for the service. An user account will grant + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: - - `AUTH_REGISTER_NEED_USERNAME_PASSWORD_EMAIL` if either no `username`, no `password` or no `email` has been supplied - - `AUTH_REGISTER_INVALID_USERNAME` if the supplied `username` does not match the given criteria (regex: [a-zA-Z0-9\-\.]{3,20}) - - `AUTH_REGISTER_INVALID_EMAIL` if the supplied `email` is not a valid email + - `REGISTER_MISSING_USERNAME` if no input for `username` was submitted + - `REGISTER_MISSING_PASSWORD` if no input for `password` was submitted + - `REGISTER_MISSING_EMAIL` if no input for `email` was submitted + - `REGISTER_INVALID_USERNAME` if the supplied `username` does not match the given criteria (regex: ^[a-zA-Z0-9\-\.]{3,20}$) + - `REGISTER_INVALID_PASSWORD` if the supplied `password` does not satisfy the given criteria (regex: ^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[a-zA-Z\d]{8,}$) + - `REGISTER_INVALID_EMAIL` if the supplied `email` is not a valid email + Schema @@ -396,7 +404,7 @@ This method can be used to register for the service. An user account will grant + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: - - `AUTH_REGISTER_USERNAME_DOES_ALREADY_EXIST` if the supplied `username` is already taken + - `REGISTER_USERNAME_DOES_ALREADY_EXIST` if the supplied `username` is already taken + Schema @@ -437,7 +445,7 @@ This method can be used to register for the service. An user account will grant + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: - - `AUTH_REGISTER_UNKNOWN_ERROR` if the account could not be created due to an internal server error + - `REGISTER_UNKNOWN_ERROR` if the account could not be created due to an internal server error + Schema @@ -482,10 +490,12 @@ This operation can only be executed by admins (rank 3). + username: `the_username` (string, required) The name of the user whos rank should be altered. + Regex: ^[a-zA-Z0-9\\-\\.]{3,20}$ + rank: `3` (enum[number], required) The new rank to apply to the submitted user. + Regex: ^[1-3]$ + Members + `1` - Normal user @@ -562,9 +572,10 @@ This operation can only be executed by admins (rank 3). + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: - - `AUTH_SETRANK_MISSING_USERNAME_RANK` if either the `username` or the `rank` has not been supplied - - `AUTH_SETRANK_NONNUMERIC_RANK` if the supplied `rank` is not of numeric type - - `AUTH_SETRANK_INVALID_RANK` if the supplied `rank` is out of the allowed range (1-3) + - `SETRANK_MISSING_USERNAME` if no input for `username` was submitted + - `SETRANK_MISSING_RANK` if no input for `rank` was submitted + - `SETRANK_INVALID_USERNAME` if the submitted `username` is malformed (regex: ^[a-zA-Z0-9\\-\\.]{3,20}$) + - `SETRANK_INVALID_RANK` if the submitted `rank` is malformed or out of range (regex: ^[1-3]$) - `USER_DOES_NOT_EXIST` if no account with the supplied `username` exists + Schema @@ -607,7 +618,7 @@ This operation can only be executed by admins (rank 3). A comprehensive list of possible errors: - `NEED_AUTHENTICATION` if no valid session token has been supplied or the user for whom the token has been created does not exist (anymore) - - `USER_INSUFFICIENT_RIGHTS_TO_SET_RANK` if the currently authenticated user has insufficient permissions (due to his rank) to perform this action + - `USER_INSUFFICIENT_PERMISSIONS` if the currently authenticated user has insufficient permissions (due to his rank) to perform this action + Schema @@ -642,9 +653,9 @@ This operation can only be executed by admins (rank 3). -# Database endpoint [/database{?offset}{?rows}{?sort}{?search}{?raw}] +# Database endpoint [/database{?offset}{?rows}{?sort}{?sortby}{?filter}{?filterby}{?raw}] -## List database entries [GET /database/{organization}/{application}/{scope}{?offset}{?rows}{?sort}{?search}] +## List database entries [GET /database/{organization}/{application}/{scope}{?offset}{?rows}{?sort}{?sortby}{?filter}{?filterby}] Returns a list of database entries. The result can be adjusted by additional, but optional parameters. @@ -661,7 +672,27 @@ Returns a list of database entries. The result can be adjusted by additional, bu + Members + `asc` + `desc` - + search (string, optional) - Only entries containing the search string in either their path, title, description, author or tags will be added to the output. + + sortby (enum[string], optional) - What criteria should be used for sorting + + Default: `key` + + Members + + `key` - Absolute entry path + + `title` - Entry title + + `created_at` - Creation date + + `author` - Authors name + + `organization` - Organization to which the application of the configuration belongs to + + `application` - Application for which the configuration is meant + + `scope` - Application internal scope + + `slug` - Entry specific unique slug + + filter (string, optional) - Only entries containing the search string in either their path, title, description, author or tags will be added to the output. + + filterby (enum[string], optional) - On what fields the filter should be applied to (i.e. what fields to involve in search) + + Default: `all` + + Members + + `all` - All fields: key, title, description, author and tags + + `key` - Only the key + + `title` - Only the title + + `description` - Only the description + + `author` - Only the authors name + + `tags` - Only tags + Response 200 (application/json) + Attributes (Entry List) @@ -697,6 +728,8 @@ Returns detailed information about the entry with the specified key (path). If t + format (string) - A configuration format, e.g. **ini** + value (string) - The configuration snippet in above mentioned format ++ Response 200 (text/plain) + + Response 404 (application/json) + Attributes (object) + status (number) - HTTP status code @@ -748,30 +781,37 @@ Can be used to create a new entry in the database. An entry consists of a unique + organization: `org.apache` (string, required) The organization which built the software for which the configuration is meant. + Regex: ^[a-zA-Z0-9\.\-]+$ + application: `hive` (string, required) The application for which the configuration is meant. + Regex: ^[a-zA-Z0-9\.\-]+$ + scope: `database` (string, required) Often different parts of an application have different configurations. Here the application specific scope can be defined. + Regex: ^[a-zA-Z0-9\.\-]+$ + slug: `sample-snippet-for-devs` (string, required) A unique slug that identifies the entry and configuration snippet further. + Regex: ^[a-zA-Z0-9\.\-]+$ + title: `Sample snippet for developers` (string, required) A title for the entry that ideally explains already what the snippet is about. + Regex: ^[^\n\r]{3,}$ + description: `This is a sample conf snippet for Apaches Hive database module.` (string, required) An extended description for the entry that explains in detail what the snippet is about. It can also contain instructions on how to use the snippet. + Regex: ^[\S\s]{3,}$ + tags: `dev`, `developer`, `db-dev` (array[string], optional) A list of tags that shall be added to the entry. Tags may be used for search, so they ideally add additional information that is not already available by the other inputs. + Regex: ^[a-z0-9\-\.]{3,20}$ + configuration: `sampleKey = sampleValue` (string, required) @@ -879,10 +919,21 @@ Can be used to create a new entry in the database. An entry consists of a unique + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: - - `ENTRY_MISSING_KEY_PARTS` if one of the four key parts (`organization`, `application`, `scope` and `slug`) is missing - - `ENTRY_MISSING_BASIC_VALUES` if one of the descriptive inputs (`title`, `description`, `configuration`) is missing - - `ENTRY_INVALID_KEY_PARTS` if one of the four key parts (`organization`, `application`, `scope` and `slug`) is malformed (regex: [a-zA-Z0-9\.\-]+). - - `ENTRY_INVALID_CONFIGURATION` if the submitted configuration snippet has an unsupported format. + - `ENTRY_MISSING_ORGANIZATION` if no input for `organization` was submitted + - `ENTRY_MISSING_APPLICATION` if no input for `application` was submitted + - `ENTRY_MISSING_SCOPE` if no input for `scope` was submitted + - `ENTRY_MISSING_SLUG` if no input for `slug` was submitted + - `ENTRY_MISSING_TITLE` if no input for `title` was submitted + - `ENTRY_MISSING_DESCRIPTION` if no input for `description` was submitted + - `ENTRY_MISSING_CONFIGURATION` if no input for `configuration` was submitted + - `ENTRY_INVALID_ORGANIZATION` if the submitted `organization` is malformed (regex: ^[a-zA-Z0-9\.\-]+$) + - `ENTRY_INVALID_APPLICATION` if the submitted `application` is malformed (regex: ^[a-zA-Z0-9\.\-]+$) + - `ENTRY_INVALID_SCOPE` if the submitted `scope` is malformed (regex: ^[a-zA-Z0-9\.\-]+$) + - `ENTRY_INVALID_SLUG` if the submitted `slug` is malformed (regex: ^[a-zA-Z0-9\.\-]+$) + - `ENTRY_INVALID_TITLE` if the submitted `title` is malformed (regex: ^[^\n\r]{3,}$) + - `ENTRY_INVALID_DESCRIPTION` if the submitted `description` is malformed (regex: ^[\s\S]{3,}$) + - `ENTRY_INVALID_TAG` if one of the submitted `tags` is malformed (regex: ^[a-z0-9\-\.]{3,20}$) + - `ENTRY_INVALID_CONFIGURATION` if the submitted configuration snippet has an unsupported format + Schema @@ -964,7 +1015,7 @@ Can be used to create a new entry in the database. An entry consists of a unique + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: - - `ENTRY_DOES_ALREADY_EXIST` if an entry with the supplied four key parts (`organization`, `application`, `scope` and `slug`) does already exist. + - `ENTRY_DOES_ALREADY_EXIST` if an entry with the supplied four key parts (`organization`, `application`, `scope` and `slug`) does already exist + Schema @@ -1015,18 +1066,21 @@ This operation can only be executed by the owner of an entry as well as moderato + title: `Sample snippet for developers` (string, required) A title for the entry that ideally explains already what the snippet is about. + Regex: ^[^\n\r]{3,}$ + description: `This is a sample conf snippet for Apaches Hive database module.` (string, required) An extended description for the entry that explains in detail what the snippet is about. It can also contain instructions on how to use the snippet. + Regex: ^[\S\s]{3,}$ + tags: `dev`, `developer`, `db-dev` (array[string], optional) A list of tags that shall be added to the entry. Tags may be used for search, so they ideally add additional information that is not already available by the other inputs. + Regex: ^[a-z0-9\-\.]{3,20}$ + configuration: `sampleKey = sampleValue` (string, required) - The configuration for which a new database entry should be created. It can be of any supported format, in this example **ini** is used. + The new configuration snippet. It can be of any supported format, in this example **ini** is used. + Schema @@ -1070,8 +1124,13 @@ This operation can only be executed by the owner of an entry as well as moderato + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: - - `ENTRY_MISSING_BASIC_VALUES` if one of the descriptive inputs (`title`, `description`, `configuration`) is missing - - `ENTRY_INVALID_CONFIGURATION` if the submitted configuration snippet has an unsupported format. + - `ENTRY_MISSING_TITLE` if no input for `title` was submitted + - `ENTRY_MISSING_DESCRIPTION` if no input for `description` was submitted + - `ENTRY_MISSING_CONFIGURATION` if no input for `configuration` was submitted + - `ENTRY_INVALID_TITLE` if the submitted `title` is malformed (regex: ^[^\n\r]{3,}$) + - `ENTRY_INVALID_DESCRIPTION` if the submitted `description` is malformed (regex: ^[\s\S]{3,}$) + - `ENTRY_INVALID_TAG` if one of the submitted `tags` is malformed (regex: ^[a-z0-9\-\.]{3,20}$) + - `ENTRY_INVALID_CONFIGURATION` if the submitted configuration snippet has an unsupported format + Schema @@ -1113,7 +1172,7 @@ This operation can only be executed by the owner of an entry as well as moderato A comprehensive list of possible errors: - `NEED_AUTHENTICATION` if no valid session token has been supplied or the user for whom the token has been created does not exist (anymore) - - `ENTRY_INSUFFICIENT_RIGHTS_TO_MANIPULATE` if the currently authenticated user has insufficient rights to update the entry (i.e. normal user, but not owner) + - `USER_INSUFFICIENT_PERMISSIONS` if the currently authenticated user has insufficient rights to update the entry (i.e. normal user, but not owner) + Schema @@ -1154,7 +1213,7 @@ This operation can only be executed by the owner of an entry as well as moderato + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: - - `ENTRY_TO_UPDATE_DOES_NOT_EXIST` if the entry that specified by the URI does not exist in the database + - `ENTRY_DOES_NOT_EXIST` if the entry specified by the URI does not exist in the database + Schema @@ -1218,7 +1277,7 @@ This operation can only be executed by the owner of an entry as well as moderato A comprehensive list of possible errors: - `NEED_AUTHENTICATION` if no valid session token has been supplied or the user for whom the token has been created does not exist (anymore) - - `ENTRY_INSUFFICIENT_RIGHTS_TO_DELETE` if the currently authenticated user has insufficient permissions to delete the entry + - `USER_INSUFFICIENT_PERMISSIONS` if the currently authenticated user has insufficient permissions to delete the entry + Schema @@ -1259,7 +1318,7 @@ This operation can only be executed by the owner of an entry as well as moderato + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: - - `ENTRY_TO_DELETE_DOES_NOT_EXIST if the entry that specified by the URI does not exist in the database + - `ENTRY_DOES_NOT_EXIST` if the entry specified by the URI does not exist in the database + Schema From c7891d1360a4793f0dd4fe87e6b79da8ffd3d49a Mon Sep 17 00:00:00 2001 From: Marvin Date: Fri, 9 Sep 2016 17:28:40 +0200 Subject: [PATCH 07/54] REST service: api-description updated (removed status in response body) --- .../snippet_sharing/api-description.apib | 166 +----------------- 1 file changed, 1 insertion(+), 165 deletions(-) diff --git a/doc/rest_api/snippet_sharing/api-description.apib b/doc/rest_api/snippet_sharing/api-description.apib index 0fc26d0f0b0..dc532b5b201 100644 --- a/doc/rest_api/snippet_sharing/api-description.apib +++ b/doc/rest_api/snippet_sharing/api-description.apib @@ -55,7 +55,6 @@ The API will try to authenticate the user by the submitted credentials. In case + Response 200 (application/json) + Attributes (object) - + status (number) - HTTP status code + token (string) - The session token which can be used to authenticate against the server in further requests + Schema @@ -63,18 +62,12 @@ The API will try to authenticate the user by the submitted credentials. In case { "type": "object", "properties": { - "status": { - "description": "HTTP status code", - "type": "integer", - "minimum": 0 - }, "token": { "description": "Session token to be used as authentication for further requests.", "type": "string" } }, "required": [ - "status", "token" ], "additionalProperties": false @@ -82,7 +75,6 @@ The API will try to authenticate the user by the submitted credentials. In case + Response 400 (application/json) + Attributes (object) - + status (number) - HTTP status code + error (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -96,11 +88,6 @@ The API will try to authenticate the user by the submitted credentials. In case { "type": "object", "properties": { - "status": { - "description": "HTTP status code", - "type": "integer", - "minimum": 0 - }, "error": { "description": "Textual description of HTTP status code", "type": "string" @@ -115,7 +102,6 @@ The API will try to authenticate the user by the submitted credentials. In case } }, "required": [ - "status", "message", "i18n" ], @@ -124,7 +110,6 @@ The API will try to authenticate the user by the submitted credentials. In case + Response 401 (application/json) + Attributes (object) - + status (number) - HTTP status code + error (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -138,11 +123,6 @@ The API will try to authenticate the user by the submitted credentials. In case { "type": "object", "properties": { - "status": { - "description": "HTTP status code", - "type": "integer", - "minimum": 0 - }, "error": { "description": "Textual description of HTTP status code", "type": "string" @@ -157,7 +137,6 @@ The API will try to authenticate the user by the submitted credentials. In case } }, "required": [ - "status", "message", "i18n" ], @@ -166,7 +145,6 @@ The API will try to authenticate the user by the submitted credentials. In case + Response 500 (application/json) + Attributes (object) - + status (number) - HTTP status code + error (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -179,11 +157,6 @@ The API will try to authenticate the user by the submitted credentials. In case { "type": "object", "properties": { - "status": { - "description": "HTTP status code", - "type": "integer", - "minimum": 0 - }, "error": { "description": "Textual description of HTTP status code", "type": "string" @@ -198,7 +171,6 @@ The API will try to authenticate the user by the submitted credentials. In case } }, "required": [ - "status", "message", "i18n" ], @@ -212,7 +184,6 @@ Retrieves the currently authenticated users details. + Response 200 (application/json) + Attributes (object) - + status (number) - HTTP status code + username (string) - The name of the currently authenticated user + rank (enum[number]) - The rank of the currently authenticated user (higher means more permissions) + Members @@ -225,11 +196,6 @@ Retrieves the currently authenticated users details. { "type": "object", "properties": { - "status": { - "description": "HTTP status code", - "type": "integer", - "minimum": 0 - }, "username": { "description": "The authenticated users name", "type": "string" @@ -240,7 +206,6 @@ Retrieves the currently authenticated users details. } }, "required": [ - "status", "username", "rank" ], @@ -249,7 +214,6 @@ Retrieves the currently authenticated users details. + Response 401 (application/json) + Attributes (object) - + status (number) - HTTP status code + error (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -262,11 +226,6 @@ Retrieves the currently authenticated users details. { "type": "object", "properties": { - "status": { - "description": "HTTP status code", - "type": "integer", - "minimum": 0 - }, "error": { "description": "Textual description of HTTP status code", "type": "string" @@ -281,7 +240,6 @@ Retrieves the currently authenticated users details. } }, "required": [ - "status", "message", "i18n" ], @@ -312,7 +270,6 @@ This method can be used to register for the service. An user account will grant + Response 200 (application/json) + Attributes (object) - + status (number) - HTTP status code + message (string) - Detailed response information, normally success message + i18n (string) - A unique token representing above message; can be used for internationalization in frontends @@ -324,11 +281,6 @@ This method can be used to register for the service. An user account will grant { "type": "object", "properties": { - "status": { - "description": "HTTP status code", - "type": "integer", - "minimum": 0 - }, "error": { "description": "Textual description of HTTP status code", "type": "string" @@ -343,7 +295,6 @@ This method can be used to register for the service. An user account will grant } }, "required": [ - "status", "message", "i18n" ], @@ -352,7 +303,6 @@ This method can be used to register for the service. An user account will grant + Response 400 (application/json) + Attributes (object) - + status (number) - HTTP status code + error (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -370,11 +320,6 @@ This method can be used to register for the service. An user account will grant { "type": "object", "properties": { - "status": { - "description": "HTTP status code", - "type": "integer", - "minimum": 0 - }, "error": { "description": "Textual description of HTTP status code", "type": "string" @@ -389,7 +334,6 @@ This method can be used to register for the service. An user account will grant } }, "required": [ - "status", "message", "i18n" ], @@ -398,7 +342,6 @@ This method can be used to register for the service. An user account will grant + Response 422 (application/json) + Attributes (object) - + status (number) - HTTP status code + error (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -411,11 +354,6 @@ This method can be used to register for the service. An user account will grant { "type": "object", "properties": { - "status": { - "description": "HTTP status code", - "type": "integer", - "minimum": 0 - }, "error": { "description": "Textual description of HTTP status code", "type": "string" @@ -430,7 +368,6 @@ This method can be used to register for the service. An user account will grant } }, "required": [ - "status", "message", "i18n" ], @@ -439,7 +376,6 @@ This method can be used to register for the service. An user account will grant + Response 500 (application/json) + Attributes (object) - + status (number) - HTTP status code + error (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -452,11 +388,6 @@ This method can be used to register for the service. An user account will grant { "type": "object", "properties": { - "status": { - "description": "HTTP status code", - "type": "integer", - "minimum": 0 - }, "error": { "description": "Textual description of HTTP status code", "type": "string" @@ -471,7 +402,6 @@ This method can be used to register for the service. An user account will grant } }, "required": [ - "status", "message", "i18n" ], @@ -525,7 +455,6 @@ This operation can only be executed by admins (rank 3). + Response 200 (application/json) + Attributes (object) - + status (number) - HTTP status code + message (string) - Detailed response information, normally success message + i18n (string) - A unique token representing above message; can be used for internationalization in frontends @@ -537,11 +466,6 @@ This operation can only be executed by admins (rank 3). { "type": "object", "properties": { - "status": { - "description": "HTTP status code", - "type": "integer", - "minimum": 0 - }, "error": { "description": "Textual description of HTTP status code", "type": "string" @@ -556,7 +480,6 @@ This operation can only be executed by admins (rank 3). } }, "required": [ - "status", "message", "i18n" ], @@ -566,7 +489,6 @@ This operation can only be executed by admins (rank 3). + Response 400 (application/json) + Attributes (object) - + status (number) - HTTP status code + error (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -583,11 +505,6 @@ This operation can only be executed by admins (rank 3). { "type": "object", "properties": { - "status": { - "description": "HTTP status code", - "type": "integer", - "minimum": 0 - }, "error": { "description": "Textual description of HTTP status code", "type": "string" @@ -602,7 +519,6 @@ This operation can only be executed by admins (rank 3). } }, "required": [ - "status", "message", "i18n" ], @@ -611,7 +527,6 @@ This operation can only be executed by admins (rank 3). + Response 401 (application/json) + Attributes (object) - + status (number) - HTTP status code + error (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -625,11 +540,6 @@ This operation can only be executed by admins (rank 3). { "type": "object", "properties": { - "status": { - "description": "HTTP status code", - "type": "integer", - "minimum": 0 - }, "error": { "description": "Textual description of HTTP status code", "type": "string" @@ -644,7 +554,6 @@ This operation can only be executed by admins (rank 3). } }, "required": [ - "status", "message", "i18n" ], @@ -711,7 +620,6 @@ Returns detailed information about the entry with the specified key (path). If t + Response 200 (application/json) + Attributes (object) - + status (number) - HTTP status code + data (object) - The actual details about the entry + key (object) - The key and its separate parts + full (string) - The full key (path) of the entry @@ -732,7 +640,6 @@ Returns detailed information about the entry with the specified key (path). If t + Response 404 (application/json) + Attributes (object) - + status (number) - HTTP status code + error (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -745,11 +652,6 @@ Returns detailed information about the entry with the specified key (path). If t { "type": "object", "properties": { - "status": { - "description": "HTTP status code", - "type": "integer", - "minimum": 0 - }, "error": { "description": "Textual description of HTTP status code", "type": "string" @@ -764,7 +666,6 @@ Returns detailed information about the entry with the specified key (path). If t } }, "required": [ - "status", "message", "i18n" ], @@ -873,7 +774,6 @@ Can be used to create a new entry in the database. An entry consists of a unique + Response 200 (application/json) + Attributes (object) - + status (number) - HTTP status code + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -885,11 +785,6 @@ Can be used to create a new entry in the database. An entry consists of a unique { "type": "object", "properties": { - "status": { - "description": "HTTP status code", - "type": "integer", - "minimum": 0 - }, "error": { "description": "Textual description of HTTP status code", "type": "string" @@ -904,7 +799,6 @@ Can be used to create a new entry in the database. An entry consists of a unique } }, "required": [ - "status", "message", "i18n" ], @@ -913,7 +807,6 @@ Can be used to create a new entry in the database. An entry consists of a unique + Response 400 (application/json) + Attributes (object) - + status (number) - HTTP status code + error (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -940,11 +833,6 @@ Can be used to create a new entry in the database. An entry consists of a unique { "type": "object", "properties": { - "status": { - "description": "HTTP status code", - "type": "integer", - "minimum": 0 - }, "error": { "description": "Textual description of HTTP status code", "type": "string" @@ -959,7 +847,6 @@ Can be used to create a new entry in the database. An entry consists of a unique } }, "required": [ - "status", "message", "i18n" ], @@ -968,7 +855,6 @@ Can be used to create a new entry in the database. An entry consists of a unique + Response 401 (application/json) + Attributes (object) - + status (number) - HTTP status code + error (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -981,11 +867,6 @@ Can be used to create a new entry in the database. An entry consists of a unique { "type": "object", "properties": { - "status": { - "description": "HTTP status code", - "type": "integer", - "minimum": 0 - }, "error": { "description": "Textual description of HTTP status code", "type": "string" @@ -1000,7 +881,6 @@ Can be used to create a new entry in the database. An entry consists of a unique } }, "required": [ - "status", "message", "i18n" ], @@ -1009,7 +889,6 @@ Can be used to create a new entry in the database. An entry consists of a unique + Response 422 (application/json) + Attributes (object) - + status (number) - HTTP status code + error (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -1022,11 +901,6 @@ Can be used to create a new entry in the database. An entry consists of a unique { "type": "object", "properties": { - "status": { - "description": "HTTP status code", - "type": "integer", - "minimum": 0 - }, "error": { "description": "Textual description of HTTP status code", "type": "string" @@ -1041,7 +915,6 @@ Can be used to create a new entry in the database. An entry consists of a unique } }, "required": [ - "status", "message", "i18n" ], @@ -1118,7 +991,6 @@ This operation can only be executed by the owner of an entry as well as moderato + Response 400 (application/json) + Attributes (object) - + status (number) - HTTP status code + error (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -1137,11 +1009,6 @@ This operation can only be executed by the owner of an entry as well as moderato { "type": "object", "properties": { - "status": { - "description": "HTTP status code", - "type": "integer", - "minimum": 0 - }, "error": { "description": "Textual description of HTTP status code", "type": "string" @@ -1156,7 +1023,6 @@ This operation can only be executed by the owner of an entry as well as moderato } }, "required": [ - "status", "message", "i18n" ], @@ -1165,7 +1031,6 @@ This operation can only be executed by the owner of an entry as well as moderato + Response 401 (application/json) + Attributes (object) - + status (number) - HTTP status code + error (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -1179,11 +1044,6 @@ This operation can only be executed by the owner of an entry as well as moderato { "type": "object", "properties": { - "status": { - "description": "HTTP status code", - "type": "integer", - "minimum": 0 - }, "error": { "description": "Textual description of HTTP status code", "type": "string" @@ -1198,7 +1058,6 @@ This operation can only be executed by the owner of an entry as well as moderato } }, "required": [ - "status", "message", "i18n" ], @@ -1207,7 +1066,6 @@ This operation can only be executed by the owner of an entry as well as moderato + Response 404 (application/json) + Attributes (object) - + status (number) - HTTP status code + error (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -1220,11 +1078,6 @@ This operation can only be executed by the owner of an entry as well as moderato { "type": "object", "properties": { - "status": { - "description": "HTTP status code", - "type": "integer", - "minimum": 0 - }, "error": { "description": "Textual description of HTTP status code", "type": "string" @@ -1239,7 +1092,6 @@ This operation can only be executed by the owner of an entry as well as moderato } }, "required": [ - "status", "message", "i18n" ], @@ -1261,7 +1113,6 @@ This operation can only be executed by the owner of an entry as well as moderato + Response 200 (application/json) + Attributes (object) - + status (number) - HTTP status code + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -1270,7 +1121,6 @@ This operation can only be executed by the owner of an entry as well as moderato + Response 401 (application/json) + Attributes (object) - + status (number) - HTTP status code + error (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -1284,11 +1134,6 @@ This operation can only be executed by the owner of an entry as well as moderato { "type": "object", "properties": { - "status": { - "description": "HTTP status code", - "type": "integer", - "minimum": 0 - }, "error": { "description": "Textual description of HTTP status code", "type": "string" @@ -1303,7 +1148,6 @@ This operation can only be executed by the owner of an entry as well as moderato } }, "required": [ - "status", "message", "i18n" ], @@ -1312,7 +1156,6 @@ This operation can only be executed by the owner of an entry as well as moderato + Response 404 (application/json) + Attributes (object) - + status (number) - HTTP status code + error (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -1325,11 +1168,6 @@ This operation can only be executed by the owner of an entry as well as moderato { "type": "object", "properties": { - "status": { - "description": "HTTP status code", - "type": "integer", - "minimum": 0 - }, "error": { "description": "Textual description of HTTP status code", "type": "string" @@ -1344,7 +1182,6 @@ This operation can only be executed by the owner of an entry as well as moderato } }, "required": [ - "status", "message", "i18n" ], @@ -1357,7 +1194,6 @@ This operation can only be executed by the owner of an entry as well as moderato ## Entry List (object) -+ status (number) - HTTP status code + elements (number) - How many entries the response list contains + entries (array[Entry Preview]) - A list of previews for entries + offset (number) - How many entries have been skipped for the output; this information can be used for pagination @@ -1371,4 +1207,4 @@ This operation can only be executed by the owner of an entry as well as moderato + title (string) - How the entry/snippet has been named by the creator + description (string) - A description of the entry + author (string) - The username of the creator of the entry -+ created_at (number) - A timestamp of when the entry has been created \ No newline at end of file ++ created_at (number) - A timestamp of when the entry has been created From 28eb67320e88faea595bd518a588c755423d82d4 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Fri, 9 Sep 2016 18:02:12 +0200 Subject: [PATCH 08/54] REST service: api-description updated (removed schema descriptions) --- .../snippet_sharing/api-description.apib | 672 ------------------ 1 file changed, 672 deletions(-) diff --git a/doc/rest_api/snippet_sharing/api-description.apib b/doc/rest_api/snippet_sharing/api-description.apib index dc532b5b201..788dacf83d7 100644 --- a/doc/rest_api/snippet_sharing/api-description.apib +++ b/doc/rest_api/snippet_sharing/api-description.apib @@ -56,22 +56,6 @@ The API will try to authenticate the user by the submitted credentials. In case + Response 200 (application/json) + Attributes (object) + token (string) - The session token which can be used to authenticate against the server in further requests - - + Schema - - { - "type": "object", - "properties": { - "token": { - "description": "Session token to be used as authentication for further requests.", - "type": "string" - } - }, - "required": [ - "token" - ], - "additionalProperties": false - } + Response 400 (application/json) + Attributes (object) @@ -83,31 +67,6 @@ The API will try to authenticate the user by the submitted credentials. In case - `AUTH_MISSING_USERNAME` if no input for `username` was submitted - `AUTH_MISSING_PASSWORD` if no input for `password` was submitted - + Schema - - { - "type": "object", - "properties": { - "error": { - "description": "Textual description of HTTP status code", - "type": "string" - }, - "message": { - "description": "Detailed information about the error.", - "type": "string" - }, - "i18n": { - "description": "Unique message token that can be used for localization in a frontend application.", - "type": "string" - } - }, - "required": [ - "message", - "i18n" - ], - "additionalProperties": false - } - + Response 401 (application/json) + Attributes (object) + error (string) - Textual description of the HTTP status @@ -117,31 +76,6 @@ The API will try to authenticate the user by the submitted credentials. In case A comprehensive list of possible errors: - `AUTH_UNKNOWN_USERNAME` if there is no user registered witht he given name - `AUTH_INVALID_PASSWORD` if the given password does not match the password saved for the given account - - + Schema - - { - "type": "object", - "properties": { - "error": { - "description": "Textual description of HTTP status code", - "type": "string" - }, - "message": { - "description": "Detailed information about the error.", - "type": "string" - }, - "i18n": { - "description": "Unique message token that can be used for localization in a frontend application.", - "type": "string" - } - }, - "required": [ - "message", - "i18n" - ], - "additionalProperties": false - } + Response 500 (application/json) + Attributes (object) @@ -152,31 +86,6 @@ The API will try to authenticate the user by the submitted credentials. In case A comprehensive list of possible errors: - `AUTH_CREATE_TOKEN_ERROR` if the session token could not be created - + Schema - - { - "type": "object", - "properties": { - "error": { - "description": "Textual description of HTTP status code", - "type": "string" - }, - "message": { - "description": "Detailed information about the error.", - "type": "string" - }, - "i18n": { - "description": "Unique message token that can be used for localization in a frontend application.", - "type": "string" - } - }, - "required": [ - "message", - "i18n" - ], - "additionalProperties": false - } - ## Retrieve current user [GET /user] @@ -190,27 +99,6 @@ Retrieves the currently authenticated users details. + `1` - Normal user + `2` - Moderator + `3` - Admin - - + Schema - - { - "type": "object", - "properties": { - "username": { - "description": "The authenticated users name", - "type": "string" - }, - "rank": { - "description": "The authenticated users rank. The higher the rank, the more permissions the user has. 1 is considered a normal user, 2 a moderator and 3 an admin.", - "enum": [1, 2, 3] - } - }, - "required": [ - "username", - "rank" - ], - "additionalProperties": false - } + Response 401 (application/json) + Attributes (object) @@ -220,31 +108,6 @@ Retrieves the currently authenticated users details. A comprehensive list of possible errors: - `NEED_AUTHENTICATION` if no valid session token has been supplied or the user for whom the token has been created does not exist (anymore) - - + Schema - - { - "type": "object", - "properties": { - "error": { - "description": "Textual description of HTTP status code", - "type": "string" - }, - "message": { - "description": "Detailed information about the error.", - "type": "string" - }, - "i18n": { - "description": "Unique message token that can be used for localization in a frontend application.", - "type": "string" - } - }, - "required": [ - "message", - "i18n" - ], - "additionalProperties": false - } ## Register [POST /register] @@ -275,31 +138,6 @@ This method can be used to register for the service. An user account will grant A comprehensive list of possible messages: - `REGISTER_USER_CREATED_SUCCESSFULLY` if the account has been created successfully - - + Schema - - { - "type": "object", - "properties": { - "error": { - "description": "Textual description of HTTP status code", - "type": "string" - }, - "message": { - "description": "Detailed information about the error.", - "type": "string" - }, - "i18n": { - "description": "Unique message token that can be used for localization in a frontend application.", - "type": "string" - } - }, - "required": [ - "message", - "i18n" - ], - "additionalProperties": false - } + Response 400 (application/json) + Attributes (object) @@ -314,31 +152,6 @@ This method can be used to register for the service. An user account will grant - `REGISTER_INVALID_USERNAME` if the supplied `username` does not match the given criteria (regex: ^[a-zA-Z0-9\-\.]{3,20}$) - `REGISTER_INVALID_PASSWORD` if the supplied `password` does not satisfy the given criteria (regex: ^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[a-zA-Z\d]{8,}$) - `REGISTER_INVALID_EMAIL` if the supplied `email` is not a valid email - - + Schema - - { - "type": "object", - "properties": { - "error": { - "description": "Textual description of HTTP status code", - "type": "string" - }, - "message": { - "description": "Detailed information about the error.", - "type": "string" - }, - "i18n": { - "description": "Unique message token that can be used for localization in a frontend application.", - "type": "string" - } - }, - "required": [ - "message", - "i18n" - ], - "additionalProperties": false - } + Response 422 (application/json) + Attributes (object) @@ -348,31 +161,6 @@ This method can be used to register for the service. An user account will grant A comprehensive list of possible errors: - `REGISTER_USERNAME_DOES_ALREADY_EXIST` if the supplied `username` is already taken - - + Schema - - { - "type": "object", - "properties": { - "error": { - "description": "Textual description of HTTP status code", - "type": "string" - }, - "message": { - "description": "Detailed information about the error.", - "type": "string" - }, - "i18n": { - "description": "Unique message token that can be used for localization in a frontend application.", - "type": "string" - } - }, - "required": [ - "message", - "i18n" - ], - "additionalProperties": false - } + Response 500 (application/json) + Attributes (object) @@ -383,31 +171,6 @@ This method can be used to register for the service. An user account will grant A comprehensive list of possible errors: - `REGISTER_UNKNOWN_ERROR` if the account could not be created due to an internal server error - + Schema - - { - "type": "object", - "properties": { - "error": { - "description": "Textual description of HTTP status code", - "type": "string" - }, - "message": { - "description": "Detailed information about the error.", - "type": "string" - }, - "i18n": { - "description": "Unique message token that can be used for localization in a frontend application.", - "type": "string" - } - }, - "required": [ - "message", - "i18n" - ], - "additionalProperties": false - } - ## Set user rank [POST /setrank] @@ -431,27 +194,6 @@ This operation can only be executed by admins (rank 3). + `1` - Normal user + `2` - Moderator + `3` - Admin - - + Schema - - { - "type": "object", - "properties": { - "username": { - "description": "The users name who shall be changed", - "type": "string" - }, - "rank": { - "description": "The new rank to apply to the user", - "enum": [1, 2, 3] - } - }, - "required": [ - "username", - "rank" - ], - "additionalProperties": false - } + Response 200 (application/json) + Attributes (object) @@ -460,32 +202,6 @@ This operation can only be executed by admins (rank 3). A comprehensive list of possible messages: - `USER_SET_RANK_SUCCESSFULLY` if the rank of the supplied user has been changed successfully - - + Schema - - { - "type": "object", - "properties": { - "error": { - "description": "Textual description of HTTP status code", - "type": "string" - }, - "message": { - "description": "Detailed information about the error.", - "type": "string" - }, - "i18n": { - "description": "Unique message token that can be used for localization in a frontend application.", - "type": "string" - } - }, - "required": [ - "message", - "i18n" - ], - "additionalProperties": false - } - + Response 400 (application/json) + Attributes (object) @@ -499,31 +215,6 @@ This operation can only be executed by admins (rank 3). - `SETRANK_INVALID_USERNAME` if the submitted `username` is malformed (regex: ^[a-zA-Z0-9\\-\\.]{3,20}$) - `SETRANK_INVALID_RANK` if the submitted `rank` is malformed or out of range (regex: ^[1-3]$) - `USER_DOES_NOT_EXIST` if no account with the supplied `username` exists - - + Schema - - { - "type": "object", - "properties": { - "error": { - "description": "Textual description of HTTP status code", - "type": "string" - }, - "message": { - "description": "Detailed information about the error.", - "type": "string" - }, - "i18n": { - "description": "Unique message token that can be used for localization in a frontend application.", - "type": "string" - } - }, - "required": [ - "message", - "i18n" - ], - "additionalProperties": false - } + Response 401 (application/json) + Attributes (object) @@ -534,31 +225,6 @@ This operation can only be executed by admins (rank 3). A comprehensive list of possible errors: - `NEED_AUTHENTICATION` if no valid session token has been supplied or the user for whom the token has been created does not exist (anymore) - `USER_INSUFFICIENT_PERMISSIONS` if the currently authenticated user has insufficient permissions (due to his rank) to perform this action - - + Schema - - { - "type": "object", - "properties": { - "error": { - "description": "Textual description of HTTP status code", - "type": "string" - }, - "message": { - "description": "Detailed information about the error.", - "type": "string" - }, - "i18n": { - "description": "Unique message token that can be used for localization in a frontend application.", - "type": "string" - } - }, - "required": [ - "message", - "i18n" - ], - "additionalProperties": false - } @@ -647,31 +313,6 @@ Returns detailed information about the entry with the specified key (path). If t A comprehensive list of possible errors: - `ENTRY_DOES_NOT_EXIST` if an entry with the given key (path) does not exist in the database - + Schema - - { - "type": "object", - "properties": { - "error": { - "description": "Textual description of HTTP status code", - "type": "string" - }, - "message": { - "description": "Detailed information about the error.", - "type": "string" - }, - "i18n": { - "description": "Unique message token that can be used for localization in a frontend application.", - "type": "string" - } - }, - "required": [ - "message", - "i18n" - ], - "additionalProperties": false - } - ## Create database entry [POST] @@ -717,60 +358,6 @@ Can be used to create a new entry in the database. An entry consists of a unique + configuration: `sampleKey = sampleValue` (string, required) The configuration for which a new database entry should be created. It can be of any supported format, in this example **ini** is used. - - + Schema - - { - "type": "object", - "properties": { - "organization": { - "description": "The organization which built the software for which the configuration is meant", - "type": "string" - }, - "application": { - "description": "The application for which the configuration is meant", - "type": "string" - }, - "scope": { - "description": "The scope within the application for which the configuration is meant", - "type": "string" - }, - "slug": { - "description": "A unique slug that identifies the entry and configuration snippet further", - "type": "string" - }, - "title": { - "description": "A title for the entry that tells what the snippet is about", - "type": "string" - }, - "description": { - "description": "An extended description for the entry that explains in detail what the snippet is about", - "type": "string" - }, - "tags": { - "description": "A list of tags that shall be added to the entry", - "type": "array", - "items": { - "type": "string" - }, - "uniqueItems": true - }, - "configuration": { - "description": "The configuration snippet in any supported format", - "type": "string" - } - }, - "required": [ - "organization", - "application", - "scope", - "slug", - "title", - "description", - "configuration" - ], - "additionalProperties": false - } + Response 200 (application/json) + Attributes (object) @@ -780,31 +367,6 @@ Can be used to create a new entry in the database. An entry consists of a unique A comprehensive list of possible messages: - `ENTRY_CREATED_SUCCESSFULLY` if the entry has been added successfully to the database - + Schema - - { - "type": "object", - "properties": { - "error": { - "description": "Textual description of HTTP status code", - "type": "string" - }, - "message": { - "description": "Detailed information about the error.", - "type": "string" - }, - "i18n": { - "description": "Unique message token that can be used for localization in a frontend application.", - "type": "string" - } - }, - "required": [ - "message", - "i18n" - ], - "additionalProperties": false - } - + Response 400 (application/json) + Attributes (object) + error (string) - Textual description of the HTTP status @@ -828,31 +390,6 @@ Can be used to create a new entry in the database. An entry consists of a unique - `ENTRY_INVALID_TAG` if one of the submitted `tags` is malformed (regex: ^[a-z0-9\-\.]{3,20}$) - `ENTRY_INVALID_CONFIGURATION` if the submitted configuration snippet has an unsupported format - + Schema - - { - "type": "object", - "properties": { - "error": { - "description": "Textual description of HTTP status code", - "type": "string" - }, - "message": { - "description": "Detailed information about the error.", - "type": "string" - }, - "i18n": { - "description": "Unique message token that can be used for localization in a frontend application.", - "type": "string" - } - }, - "required": [ - "message", - "i18n" - ], - "additionalProperties": false - } - + Response 401 (application/json) + Attributes (object) + error (string) - Textual description of the HTTP status @@ -862,31 +399,6 @@ Can be used to create a new entry in the database. An entry consists of a unique A comprehensive list of possible errors: - `NEED_AUTHENTICATION` if no valid session token has been supplied or the user for whom the token has been created does not exist (anymore) - + Schema - - { - "type": "object", - "properties": { - "error": { - "description": "Textual description of HTTP status code", - "type": "string" - }, - "message": { - "description": "Detailed information about the error.", - "type": "string" - }, - "i18n": { - "description": "Unique message token that can be used for localization in a frontend application.", - "type": "string" - } - }, - "required": [ - "message", - "i18n" - ], - "additionalProperties": false - } - + Response 422 (application/json) + Attributes (object) + error (string) - Textual description of the HTTP status @@ -895,31 +407,6 @@ Can be used to create a new entry in the database. An entry consists of a unique A comprehensive list of possible errors: - `ENTRY_DOES_ALREADY_EXIST` if an entry with the supplied four key parts (`organization`, `application`, `scope` and `slug`) does already exist - - + Schema - - { - "type": "object", - "properties": { - "error": { - "description": "Textual description of HTTP status code", - "type": "string" - }, - "message": { - "description": "Detailed information about the error.", - "type": "string" - }, - "i18n": { - "description": "Unique message token that can be used for localization in a frontend application.", - "type": "string" - } - }, - "required": [ - "message", - "i18n" - ], - "additionalProperties": false - } ## Update an existing entry [PUT /database/{organization}/{application}/{scope}/{slug}] @@ -954,40 +441,6 @@ This operation can only be executed by the owner of an entry as well as moderato + configuration: `sampleKey = sampleValue` (string, required) The new configuration snippet. It can be of any supported format, in this example **ini** is used. - - + Schema - - { - "type": "object", - "properties": { - "title": { - "description": "A title for the entry that tells what the snippet is about", - "type": "string" - }, - "description": { - "description": "An extended description for the entry that explains in detail what the snippet is about", - "type": "string" - }, - "tags": { - "description": "A list of tags that shall be added to the entry", - "type": "array", - "items": { - "type": "string" - }, - "uniqueItems": true - }, - "configuration": { - "description": "The configuration snippet in any supported format", - "type": "string" - } - }, - "required": [ - "title", - "description", - "configuration" - ], - "additionalProperties": false - } + Response 400 (application/json) + Attributes (object) @@ -1004,31 +457,6 @@ This operation can only be executed by the owner of an entry as well as moderato - `ENTRY_INVALID_TAG` if one of the submitted `tags` is malformed (regex: ^[a-z0-9\-\.]{3,20}$) - `ENTRY_INVALID_CONFIGURATION` if the submitted configuration snippet has an unsupported format - + Schema - - { - "type": "object", - "properties": { - "error": { - "description": "Textual description of HTTP status code", - "type": "string" - }, - "message": { - "description": "Detailed information about the error.", - "type": "string" - }, - "i18n": { - "description": "Unique message token that can be used for localization in a frontend application.", - "type": "string" - } - }, - "required": [ - "message", - "i18n" - ], - "additionalProperties": false - } - + Response 401 (application/json) + Attributes (object) + error (string) - Textual description of the HTTP status @@ -1039,31 +467,6 @@ This operation can only be executed by the owner of an entry as well as moderato - `NEED_AUTHENTICATION` if no valid session token has been supplied or the user for whom the token has been created does not exist (anymore) - `USER_INSUFFICIENT_PERMISSIONS` if the currently authenticated user has insufficient rights to update the entry (i.e. normal user, but not owner) - + Schema - - { - "type": "object", - "properties": { - "error": { - "description": "Textual description of HTTP status code", - "type": "string" - }, - "message": { - "description": "Detailed information about the error.", - "type": "string" - }, - "i18n": { - "description": "Unique message token that can be used for localization in a frontend application.", - "type": "string" - } - }, - "required": [ - "message", - "i18n" - ], - "additionalProperties": false - } - + Response 404 (application/json) + Attributes (object) + error (string) - Textual description of the HTTP status @@ -1073,31 +476,6 @@ This operation can only be executed by the owner of an entry as well as moderato A comprehensive list of possible errors: - `ENTRY_DOES_NOT_EXIST` if the entry specified by the URI does not exist in the database - + Schema - - { - "type": "object", - "properties": { - "error": { - "description": "Textual description of HTTP status code", - "type": "string" - }, - "message": { - "description": "Detailed information about the error.", - "type": "string" - }, - "i18n": { - "description": "Unique message token that can be used for localization in a frontend application.", - "type": "string" - } - }, - "required": [ - "message", - "i18n" - ], - "additionalProperties": false - } - ## Delete an entry [DELETE /database/{organization}/{application}/{scope}/{slug}] @@ -1128,31 +506,6 @@ This operation can only be executed by the owner of an entry as well as moderato A comprehensive list of possible errors: - `NEED_AUTHENTICATION` if no valid session token has been supplied or the user for whom the token has been created does not exist (anymore) - `USER_INSUFFICIENT_PERMISSIONS` if the currently authenticated user has insufficient permissions to delete the entry - - + Schema - - { - "type": "object", - "properties": { - "error": { - "description": "Textual description of HTTP status code", - "type": "string" - }, - "message": { - "description": "Detailed information about the error.", - "type": "string" - }, - "i18n": { - "description": "Unique message token that can be used for localization in a frontend application.", - "type": "string" - } - }, - "required": [ - "message", - "i18n" - ], - "additionalProperties": false - } + Response 404 (application/json) + Attributes (object) @@ -1162,31 +515,6 @@ This operation can only be executed by the owner of an entry as well as moderato A comprehensive list of possible errors: - `ENTRY_DOES_NOT_EXIST` if the entry specified by the URI does not exist in the database - - + Schema - - { - "type": "object", - "properties": { - "error": { - "description": "Textual description of HTTP status code", - "type": "string" - }, - "message": { - "description": "Detailed information about the error.", - "type": "string" - }, - "i18n": { - "description": "Unique message token that can be used for localization in a frontend application.", - "type": "string" - } - }, - "required": [ - "message", - "i18n" - ], - "additionalProperties": false - } From 7be4c8cc54109feef7e8b1dee65cd5a8772ddb0e Mon Sep 17 00:00:00 2001 From: Namoshek Date: Sat, 10 Sep 2016 11:20:39 +0200 Subject: [PATCH 09/54] REST service: api-description updated (removed obsolete schema) --- .../snippet_sharing/api-description.apib | 23 +------------------ 1 file changed, 1 insertion(+), 22 deletions(-) diff --git a/doc/rest_api/snippet_sharing/api-description.apib b/doc/rest_api/snippet_sharing/api-description.apib index 788dacf83d7..fbd15b33b4c 100644 --- a/doc/rest_api/snippet_sharing/api-description.apib +++ b/doc/rest_api/snippet_sharing/api-description.apib @@ -19,7 +19,7 @@ Returns an overview of available API methods with required parameters and a desc ## Authenticate [POST] -The API will try to authenticate the user by the submitted credentials. In case of success a session token (JWT) will be returned, which can be used for further requests to the API. +The API will try to authenticate the user by the submitted credentials. In case of success a session token will be returned, which can be used for further requests to the API. + Request (application/json) + Attributes (object) @@ -31,27 +31,6 @@ The API will try to authenticate the user by the submitted credentials. In case + password: `a5ecretP4ssword` (string, required) The corresponding password for the supplied user account. - - + Schema - - { - "type": "object", - "properties": { - "username": { - "description": "Name of the user that wants to authenticate", - "type": "string" - }, - "password": { - "description": "Password for the username in question", - "type": "string" - } - }, - "required": [ - "username", - "password" - ], - "additionalProperties": false - } + Response 200 (application/json) + Attributes (object) From bd0acc0da3c7aadbe8839e66a090bf0e83c66517 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Sat, 10 Sep 2016 11:58:27 +0200 Subject: [PATCH 10/54] REST service: api-description updated (new users endpoint with more functionality, some taken of the old authentication endpoint) --- .../snippet_sharing/api-description.apib | 174 +++++++++++------- 1 file changed, 112 insertions(+), 62 deletions(-) diff --git a/doc/rest_api/snippet_sharing/api-description.apib b/doc/rest_api/snippet_sharing/api-description.apib index fbd15b33b4c..a0c39b137d5 100644 --- a/doc/rest_api/snippet_sharing/api-description.apib +++ b/doc/rest_api/snippet_sharing/api-description.apib @@ -19,13 +19,14 @@ Returns an overview of available API methods with required parameters and a desc ## Authenticate [POST] -The API will try to authenticate the user by the submitted credentials. In case of success a session token will be returned, which can be used for further requests to the API. +The API will try to authenticate the user by the submitted credentials. In case of success a session token, which can be used for further requests to the API, will be returned. + Request (application/json) + Attributes (object) + username: `the-username` (string, required) The name of the user account which should be tried to authenticate. + Regex: ^[a-zA-Z0-9\-\.]{3,20}$ + password: `a5ecretP4ssword` (string, required) @@ -38,7 +39,7 @@ The API will try to authenticate the user by the submitted credentials. In case + Response 400 (application/json) + Attributes (object) - + error (string) - Textual description of the HTTP status + + status (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -48,7 +49,7 @@ The API will try to authenticate the user by the submitted credentials. In case + Response 401 (application/json) + Attributes (object) - + error (string) - Textual description of the HTTP status + + status (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -56,24 +57,52 @@ The API will try to authenticate the user by the submitted credentials. In case - `AUTH_UNKNOWN_USERNAME` if there is no user registered witht he given name - `AUTH_INVALID_PASSWORD` if the given password does not match the password saved for the given account -+ Response 500 (application/json) - + Attributes (object) - + error (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request - + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends - A comprehensive list of possible errors: - - `AUTH_CREATE_TOKEN_ERROR` if the session token could not be created +# Users endpoint [/users{?rows}{?sort}{?sortby}{?filter}{?filterby}{?current}] + +## User list [GET] + +Retrieves a list of users. The result can be adjusted by additional, but optional parameters. This operation requires moderator permissions (rank 2) or higher. + ++ Parameters + + rows (number, optional) - How many entries will be added to the output at max. + + Default: `200` + + sort (enum[string], optional) - How to sort the entries for the output. + + Default: `asc` + + Members + + `asc` + + `desc` + + sortby (enum[string], optional) - What criteria should be used for sorting + + Default: `username` + + Members + + `username` - The users name + + `email` - email + + `created_at` - Creation date + + filter (string, optional) - Only users containing the search string in either their name or their email will be added to the output. + + filterby (enum[string], optional) - On what fields the filter should be applied to (i.e. what fields to involve in search) + + Default: `all` + + Members + + `all` - All fields: username and email + + `username` - Only the username + + `email` - Only the email + ++ Response 200 (application/json) + + Attributes (User List) +## Retrieve user details [GET /{name}{?current}] -## Retrieve current user [GET /user] +Retrieves the details of the specified user. If the parameter `current` is specified, the currently authenticated user will be chosen as target. Retrieving details of other users requires moderator permissions (rank 2) or higher. -Retrieves the currently authenticated users details. ++ Parameters + + current (boolean, optional) - If the currently authenticated users details should be fetched + + Default: `false` + + name (string, required) - The `username` of the user whose details should be fetched + Response 200 (application/json) + Attributes (object) - + username (string) - The name of the currently authenticated user - + rank (enum[number]) - The rank of the currently authenticated user (higher means more permissions) + + username (string) - The name of the user + + email (string) - The email of the user + + rank (enum[number]) - The rank of the user (higher means more permissions) + Members + `1` - Normal user + `2` - Moderator @@ -81,7 +110,7 @@ Retrieves the currently authenticated users details. + Response 401 (application/json) + Attributes (object) - + error (string) - Textual description of the HTTP status + + status (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -89,21 +118,23 @@ Retrieves the currently authenticated users details. - `NEED_AUTHENTICATION` if no valid session token has been supplied or the user for whom the token has been created does not exist (anymore) -## Register [POST /register] +## Create user [POST] -This method can be used to register for the service. An user account will grant access to more functions. +This method can be used to register for the service by creating a new user account. An user account will grant access to more functions. + Request (application/json) + Attributes (object) + username: `the_username` (string, required) The username must be between 3 and 20 signs long and may contain only letters a-z (lower- and upper-case), the numbers 0-9 and dots (.) as well as dashes (-). + Regex: ^[a-zA-Z0-9\-\.]{3,20}$ + password: `somePassword` (string, required) The password must be at least 8 signs long and contain at least one lower-case letter, one upper-case letter and one digit. To harden security, the user is encouraged to use special characters as well. + Regex: ^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[a-zA-Z\d]{8,}$ + email: `an@email.com` (string, required) @@ -116,57 +147,55 @@ This method can be used to register for the service. An user account will grant + i18n (string) - A unique token representing above message; can be used for internationalization in frontends A comprehensive list of possible messages: - - `REGISTER_USER_CREATED_SUCCESSFULLY` if the account has been created successfully + - `USER_CREATED_SUCCESSFULLY` if the account has been created successfully + Response 400 (application/json) + Attributes (object) - + error (string) - Textual description of the HTTP status + + status (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: - - `REGISTER_MISSING_USERNAME` if no input for `username` was submitted - - `REGISTER_MISSING_PASSWORD` if no input for `password` was submitted - - `REGISTER_MISSING_EMAIL` if no input for `email` was submitted - - `REGISTER_INVALID_USERNAME` if the supplied `username` does not match the given criteria (regex: ^[a-zA-Z0-9\-\.]{3,20}$) - - `REGISTER_INVALID_PASSWORD` if the supplied `password` does not satisfy the given criteria (regex: ^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[a-zA-Z\d]{8,}$) - - `REGISTER_INVALID_EMAIL` if the supplied `email` is not a valid email + - `USER_CREATE_MISSING_USERNAME` if no input for `username` was submitted + - `USER_CREATE_MISSING_PASSWORD` if no input for `password` was submitted + - `USER_CREATE_MISSING_EMAIL` if no input for `email` was submitted + - `USER_CREATE_INVALID_USERNAME` if the supplied `username` does not match the given criteria (regex: ^[a-zA-Z0-9\-\.]{3,20}$) + - `USER_CREATE_INVALID_PASSWORD` if the supplied `password` does not satisfy the given criteria (regex: ^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[a-zA-Z\d]{8,}$) + - `USER_CREATE_INVALID_EMAIL` if the supplied `email` is not a valid email + Response 422 (application/json) + Attributes (object) - + error (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request - + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends - - A comprehensive list of possible errors: - - `REGISTER_USERNAME_DOES_ALREADY_EXIST` if the supplied `username` is already taken - -+ Response 500 (application/json) - + Attributes (object) - + error (string) - Textual description of the HTTP status + + status (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: - - `REGISTER_UNKNOWN_ERROR` if the account could not be created due to an internal server error + - `USER_CREATE_USERNAME_DOES_ALREADY_EXIST` if the supplied `username` is already taken -## Set user rank [POST /setrank] +## Update user [PUT /{name}] -This method can be used to change the rank of an user. The higher the rank, the more permissions an user has. Rank 1 is considered a normal user, 2 a moderator and 3 an admin. +This method can be used to edit an user. If no `name` is supplied, the currently authenticated user is chosen as target. By using this method it is also possible to change the rank of users. Changing the rank as well as other users in general can only be done by admins (rank 3) though. -This operation can only be executed by admins (rank 3). ++ Parameters + + name (string, optional) - The `username` of an user which is then taken as target for the operation + Request (application/json) + Attributes (object) - + username: `the_username` (string, required) + + email: `a-new@email.com` (string, optional) - The name of the user whos rank should be altered. - Regex: ^[a-zA-Z0-9\\-\\.]{3,20}$ + The new email address which should be used for the user. It has to be a valid email. + + + password: `a_new-secureP4ssw0rd` (string, optional) + + The new password for the user. + + Regex: ^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[a-zA-Z\d]{8,}$ - + rank: `3` (enum[number], required) + + rank: `3` (enum[number], optional) - The new rank to apply to the submitted user. + The new rank which should be set for the user. Setting this parameter does only result in a change if the currently authenticated user has the permission to change ranks. + Regex: ^[1-3]$ + Members @@ -180,24 +209,22 @@ This operation can only be executed by admins (rank 3). + i18n (string) - A unique token representing above message; can be used for internationalization in frontends A comprehensive list of possible messages: - - `USER_SET_RANK_SUCCESSFULLY` if the rank of the supplied user has been changed successfully + - `USER_UPDATED_SUCCESSFULLY` if the changes to the user have been stored successfully + Response 400 (application/json) + Attributes (object) - + error (string) - Textual description of the HTTP status + + status (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: - - `SETRANK_MISSING_USERNAME` if no input for `username` was submitted - - `SETRANK_MISSING_RANK` if no input for `rank` was submitted - - `SETRANK_INVALID_USERNAME` if the submitted `username` is malformed (regex: ^[a-zA-Z0-9\\-\\.]{3,20}$) - - `SETRANK_INVALID_RANK` if the submitted `rank` is malformed or out of range (regex: ^[1-3]$) - - `USER_DOES_NOT_EXIST` if no account with the supplied `username` exists + - `USER_UPDATE_INVALID_PASSWORD` if the supplied `password` does not satisfy the given criteria (regex: ^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[a-zA-Z\d]{8,}$) + - `USER_UPDATE_INVALID_EMAIL` if the supplied `email` is not a valid email + - `USER_UPDATE_INVALID_RANK` if the supplied `rank` is not a valid rank (regex: ^[1-3]$) + Response 401 (application/json) + Attributes (object) - + error (string) - Textual description of the HTTP status + + status (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -285,7 +312,7 @@ Returns detailed information about the entry with the specified key (path). If t + Response 404 (application/json) + Attributes (object) - + error (string) - Textual description of the HTTP status + + status (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -302,36 +329,43 @@ Can be used to create a new entry in the database. An entry consists of a unique + organization: `org.apache` (string, required) The organization which built the software for which the configuration is meant. + Regex: ^[a-zA-Z0-9\.\-]+$ + application: `hive` (string, required) The application for which the configuration is meant. + Regex: ^[a-zA-Z0-9\.\-]+$ + scope: `database` (string, required) Often different parts of an application have different configurations. Here the application specific scope can be defined. + Regex: ^[a-zA-Z0-9\.\-]+$ + slug: `sample-snippet-for-devs` (string, required) A unique slug that identifies the entry and configuration snippet further. + Regex: ^[a-zA-Z0-9\.\-]+$ + title: `Sample snippet for developers` (string, required) A title for the entry that ideally explains already what the snippet is about. + Regex: ^[^\n\r]{3,}$ + description: `This is a sample conf snippet for Apaches Hive database module.` (string, required) An extended description for the entry that explains in detail what the snippet is about. It can also contain instructions on how to use the snippet. + Regex: ^[\S\s]{3,}$ + tags: `dev`, `developer`, `db-dev` (array[string], optional) A list of tags that shall be added to the entry. Tags may be used for search, so they ideally add additional information that is not already available by the other inputs. + Regex: ^[a-z0-9\-\.]{3,20}$ + configuration: `sampleKey = sampleValue` (string, required) @@ -348,7 +382,7 @@ Can be used to create a new entry in the database. An entry consists of a unique + Response 400 (application/json) + Attributes (object) - + error (string) - Textual description of the HTTP status + + status (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -371,7 +405,7 @@ Can be used to create a new entry in the database. An entry consists of a unique + Response 401 (application/json) + Attributes (object) - + error (string) - Textual description of the HTTP status + + status (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -380,7 +414,7 @@ Can be used to create a new entry in the database. An entry consists of a unique + Response 422 (application/json) + Attributes (object) - + error (string) - Textual description of the HTTP status + + status (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -405,16 +439,19 @@ This operation can only be executed by the owner of an entry as well as moderato + title: `Sample snippet for developers` (string, required) A title for the entry that ideally explains already what the snippet is about. + Regex: ^[^\n\r]{3,}$ + description: `This is a sample conf snippet for Apaches Hive database module.` (string, required) An extended description for the entry that explains in detail what the snippet is about. It can also contain instructions on how to use the snippet. + Regex: ^[\S\s]{3,}$ + tags: `dev`, `developer`, `db-dev` (array[string], optional) A list of tags that shall be added to the entry. Tags may be used for search, so they ideally add additional information that is not already available by the other inputs. + Regex: ^[a-z0-9\-\.]{3,20}$ + configuration: `sampleKey = sampleValue` (string, required) @@ -423,7 +460,7 @@ This operation can only be executed by the owner of an entry as well as moderato + Response 400 (application/json) + Attributes (object) - + error (string) - Textual description of the HTTP status + + status (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -438,7 +475,7 @@ This operation can only be executed by the owner of an entry as well as moderato + Response 401 (application/json) + Attributes (object) - + error (string) - Textual description of the HTTP status + + status (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -448,7 +485,7 @@ This operation can only be executed by the owner of an entry as well as moderato + Response 404 (application/json) + Attributes (object) - + error (string) - Textual description of the HTTP status + + status (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -478,7 +515,7 @@ This operation can only be executed by the owner of an entry as well as moderato + Response 401 (application/json) + Attributes (object) - + error (string) - Textual description of the HTTP status + + status (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -488,7 +525,7 @@ This operation can only be executed by the owner of an entry as well as moderato + Response 404 (application/json) + Attributes (object) - + error (string) - Textual description of the HTTP status + + status (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -499,6 +536,19 @@ This operation can only be executed by the owner of an entry as well as moderato # Data Structures +## User List (object) + ++ elements (number) - How many users the response list contains ++ users (array[User Preview]) - A list of previews for users ++ offset (number) - How many entries have been skipped for the output; this information can be used for pagination ++ remaining (number) - How many entries have not been displayed yet; when adding this value to the offset (and not exceeding the row limit), all entries should have been displayed once + +## User Preview (object) + ++ username (string) - The users name ++ email (string) - The users email ++ created_at (number) - A timestamp of the moment when the entry has been created + ## Entry List (object) + elements (number) - How many entries the response list contains @@ -514,4 +564,4 @@ This operation can only be executed by the owner of an entry as well as moderato + title (string) - How the entry/snippet has been named by the creator + description (string) - A description of the entry + author (string) - The username of the creator of the entry -+ created_at (number) - A timestamp of when the entry has been created ++ created_at (number) - A timestamp of the moment when the entry has been created From 1398ae4f4512c5c309d92f4ae4ae500f3b7d576c Mon Sep 17 00:00:00 2001 From: Namoshek Date: Sat, 10 Sep 2016 16:23:59 +0200 Subject: [PATCH 11/54] REST service: api-description updated (error for unsupported raw format added) --- doc/rest_api/snippet_sharing/api-description.apib | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/doc/rest_api/snippet_sharing/api-description.apib b/doc/rest_api/snippet_sharing/api-description.apib index a0c39b137d5..e8f4ff426f9 100644 --- a/doc/rest_api/snippet_sharing/api-description.apib +++ b/doc/rest_api/snippet_sharing/api-description.apib @@ -310,6 +310,15 @@ Returns detailed information about the entry with the specified key (path). If t + Response 200 (text/plain) ++ Response 401 (application/json) + + Attributes (object) + + status (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `ENTRY_UNSUPPORTED_FORMAT` if an unsupported `raw` format has been supplied + + Response 404 (application/json) + Attributes (object) + status (string) - Textual description of the HTTP status From f8369a1deec8888abbd890e427dec73dbc64398e Mon Sep 17 00:00:00 2001 From: Namoshek Date: Mon, 12 Sep 2016 09:15:14 +0200 Subject: [PATCH 12/54] REST service: api-description updated (added resource to query API version) --- doc/rest_api/snippet_sharing/api-description.apib | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/doc/rest_api/snippet_sharing/api-description.apib b/doc/rest_api/snippet_sharing/api-description.apib index e8f4ff426f9..c136c00bcb6 100644 --- a/doc/rest_api/snippet_sharing/api-description.apib +++ b/doc/rest_api/snippet_sharing/api-description.apib @@ -14,6 +14,17 @@ Returns an overview of available API methods with required parameters and a desc + Response 200 (text/html; charset=utf-8) +## API Version [GET /version] + +Returns the currently used version of the API. A version consists of two numbers (format: a.b), where the first number (a) is the major version and the second number (b) the minor version. Minor versions may not contain breaking changes (i.e. backwards-compatibility is ensured), but major versions may. This means that minor versions may only extend the API. + ++ Response 200 (application/json) + + Attributes (object) + + version (string) - The currently used version in its complete format + + major (number) - The currently used major version + + minor (number) - The currently used minor version + + # Authentication endpoint [/auth] From 7f09d2ddf59a52aa9186315a2c5b7f29cd9d73bd Mon Sep 17 00:00:00 2001 From: Namoshek Date: Mon, 12 Sep 2016 11:12:18 +0200 Subject: [PATCH 13/54] REST service: api-description updated (added error code for unsupported Content-Type in request) --- doc/rest_api/snippet_sharing/api-description.apib | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/doc/rest_api/snippet_sharing/api-description.apib b/doc/rest_api/snippet_sharing/api-description.apib index c136c00bcb6..5c82be52015 100644 --- a/doc/rest_api/snippet_sharing/api-description.apib +++ b/doc/rest_api/snippet_sharing/api-description.apib @@ -57,6 +57,7 @@ The API will try to authenticate the user by the submitted credentials. In case A comprehensive list of possible errors: - `AUTH_MISSING_USERNAME` if no input for `username` was submitted - `AUTH_MISSING_PASSWORD` if no input for `password` was submitted + - `REQUEST_UNSUPPORTED_CONTENT_TYPE` if the submitted content and/or Content-Type is not `application/json` + Response 401 (application/json) + Attributes (object) @@ -173,6 +174,7 @@ This method can be used to register for the service by creating a new user accou - `USER_CREATE_INVALID_USERNAME` if the supplied `username` does not match the given criteria (regex: ^[a-zA-Z0-9\-\.]{3,20}$) - `USER_CREATE_INVALID_PASSWORD` if the supplied `password` does not satisfy the given criteria (regex: ^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[a-zA-Z\d]{8,}$) - `USER_CREATE_INVALID_EMAIL` if the supplied `email` is not a valid email + - `REQUEST_UNSUPPORTED_CONTENT_TYPE` if the submitted content and/or Content-Type is not `application/json` + Response 422 (application/json) + Attributes (object) @@ -232,6 +234,7 @@ This method can be used to edit an user. If no `name` is supplied, the currently - `USER_UPDATE_INVALID_PASSWORD` if the supplied `password` does not satisfy the given criteria (regex: ^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[a-zA-Z\d]{8,}$) - `USER_UPDATE_INVALID_EMAIL` if the supplied `email` is not a valid email - `USER_UPDATE_INVALID_RANK` if the supplied `rank` is not a valid rank (regex: ^[1-3]$) + - `REQUEST_UNSUPPORTED_CONTENT_TYPE` if the submitted content and/or Content-Type is not `application/json` + Response 401 (application/json) + Attributes (object) @@ -321,7 +324,7 @@ Returns detailed information about the entry with the specified key (path). If t + Response 200 (text/plain) -+ Response 401 (application/json) ++ Response 400 (application/json) + Attributes (object) + status (string) - Textual description of the HTTP status + message (string) - Detailed error information, e.g. hint about malformed request @@ -422,6 +425,7 @@ Can be used to create a new entry in the database. An entry consists of a unique - `ENTRY_INVALID_DESCRIPTION` if the submitted `description` is malformed (regex: ^[\s\S]{3,}$) - `ENTRY_INVALID_TAG` if one of the submitted `tags` is malformed (regex: ^[a-z0-9\-\.]{3,20}$) - `ENTRY_INVALID_CONFIGURATION` if the submitted configuration snippet has an unsupported format + - `REQUEST_UNSUPPORTED_CONTENT_TYPE` if the submitted content and/or Content-Type is not `application/json` + Response 401 (application/json) + Attributes (object) @@ -492,6 +496,7 @@ This operation can only be executed by the owner of an entry as well as moderato - `ENTRY_INVALID_DESCRIPTION` if the submitted `description` is malformed (regex: ^[\s\S]{3,}$) - `ENTRY_INVALID_TAG` if one of the submitted `tags` is malformed (regex: ^[a-z0-9\-\.]{3,20}$) - `ENTRY_INVALID_CONFIGURATION` if the submitted configuration snippet has an unsupported format + - `REQUEST_UNSUPPORTED_CONTENT_TYPE` if the submitted content and/or Content-Type is not `application/json` + Response 401 (application/json) + Attributes (object) From 91a4bc63b61190eedbbdbe470ae0a0f91f07ae88 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Mon, 12 Sep 2016 15:06:16 +0200 Subject: [PATCH 14/54] REST service: api-description updated (added new response type for wrong content-type) --- .../snippet_sharing/api-description.apib | 56 +++++++++++++++++-- 1 file changed, 51 insertions(+), 5 deletions(-) diff --git a/doc/rest_api/snippet_sharing/api-description.apib b/doc/rest_api/snippet_sharing/api-description.apib index 5c82be52015..1d1bc28dcd9 100644 --- a/doc/rest_api/snippet_sharing/api-description.apib +++ b/doc/rest_api/snippet_sharing/api-description.apib @@ -57,7 +57,7 @@ The API will try to authenticate the user by the submitted credentials. In case A comprehensive list of possible errors: - `AUTH_MISSING_USERNAME` if no input for `username` was submitted - `AUTH_MISSING_PASSWORD` if no input for `password` was submitted - - `REQUEST_UNSUPPORTED_CONTENT_TYPE` if the submitted content and/or Content-Type is not `application/json` + - `REQUEST_MALFORMED_DATA` if the submitted data in the request body does not match the Content-Type or is unparseable + Response 401 (application/json) + Attributes (object) @@ -69,6 +69,16 @@ The API will try to authenticate the user by the submitted credentials. In case - `AUTH_UNKNOWN_USERNAME` if there is no user registered witht he given name - `AUTH_INVALID_PASSWORD` if the given password does not match the password saved for the given account ++ Response 406 (application/json) + + Attributes (object) + + status (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `REQUEST_UNSUPPORTED_CONTENT_TYPE` if the submitted Content-Type is not `application/json` + + # Users endpoint [/users{?rows}{?sort}{?sortby}{?filter}{?filterby}{?current}] @@ -174,7 +184,16 @@ This method can be used to register for the service by creating a new user accou - `USER_CREATE_INVALID_USERNAME` if the supplied `username` does not match the given criteria (regex: ^[a-zA-Z0-9\-\.]{3,20}$) - `USER_CREATE_INVALID_PASSWORD` if the supplied `password` does not satisfy the given criteria (regex: ^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[a-zA-Z\d]{8,}$) - `USER_CREATE_INVALID_EMAIL` if the supplied `email` is not a valid email - - `REQUEST_UNSUPPORTED_CONTENT_TYPE` if the submitted content and/or Content-Type is not `application/json` + - `REQUEST_MALFORMED_DATA` if the submitted data in the request body does not match the Content-Type or is unparseable + ++ Response 406 (application/json) + + Attributes (object) + + status (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `REQUEST_UNSUPPORTED_CONTENT_TYPE` if the submitted Content-Type is not `application/json` + Response 422 (application/json) + Attributes (object) @@ -234,7 +253,7 @@ This method can be used to edit an user. If no `name` is supplied, the currently - `USER_UPDATE_INVALID_PASSWORD` if the supplied `password` does not satisfy the given criteria (regex: ^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[a-zA-Z\d]{8,}$) - `USER_UPDATE_INVALID_EMAIL` if the supplied `email` is not a valid email - `USER_UPDATE_INVALID_RANK` if the supplied `rank` is not a valid rank (regex: ^[1-3]$) - - `REQUEST_UNSUPPORTED_CONTENT_TYPE` if the submitted content and/or Content-Type is not `application/json` + - `REQUEST_MALFORMED_DATA` if the submitted data in the request body does not match the Content-Type or is unparseable + Response 401 (application/json) + Attributes (object) @@ -246,6 +265,15 @@ This method can be used to edit an user. If no `name` is supplied, the currently - `NEED_AUTHENTICATION` if no valid session token has been supplied or the user for whom the token has been created does not exist (anymore) - `USER_INSUFFICIENT_PERMISSIONS` if the currently authenticated user has insufficient permissions (due to his rank) to perform this action ++ Response 406 (application/json) + + Attributes (object) + + status (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `REQUEST_UNSUPPORTED_CONTENT_TYPE` if the submitted Content-Type is not `application/json` + # Database endpoint [/database{?offset}{?rows}{?sort}{?sortby}{?filter}{?filterby}{?raw}] @@ -425,7 +453,7 @@ Can be used to create a new entry in the database. An entry consists of a unique - `ENTRY_INVALID_DESCRIPTION` if the submitted `description` is malformed (regex: ^[\s\S]{3,}$) - `ENTRY_INVALID_TAG` if one of the submitted `tags` is malformed (regex: ^[a-z0-9\-\.]{3,20}$) - `ENTRY_INVALID_CONFIGURATION` if the submitted configuration snippet has an unsupported format - - `REQUEST_UNSUPPORTED_CONTENT_TYPE` if the submitted content and/or Content-Type is not `application/json` + - `REQUEST_MALFORMED_DATA` if the submitted data in the request body does not match the Content-Type or is unparseable + Response 401 (application/json) + Attributes (object) @@ -436,6 +464,15 @@ Can be used to create a new entry in the database. An entry consists of a unique A comprehensive list of possible errors: - `NEED_AUTHENTICATION` if no valid session token has been supplied or the user for whom the token has been created does not exist (anymore) ++ Response 406 (application/json) + + Attributes (object) + + status (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `REQUEST_UNSUPPORTED_CONTENT_TYPE` if the submitted Content-Type is not `application/json` + + Response 422 (application/json) + Attributes (object) + status (string) - Textual description of the HTTP status @@ -496,7 +533,7 @@ This operation can only be executed by the owner of an entry as well as moderato - `ENTRY_INVALID_DESCRIPTION` if the submitted `description` is malformed (regex: ^[\s\S]{3,}$) - `ENTRY_INVALID_TAG` if one of the submitted `tags` is malformed (regex: ^[a-z0-9\-\.]{3,20}$) - `ENTRY_INVALID_CONFIGURATION` if the submitted configuration snippet has an unsupported format - - `REQUEST_UNSUPPORTED_CONTENT_TYPE` if the submitted content and/or Content-Type is not `application/json` + - `REQUEST_MALFORMED_DATA` if the submitted data in the request body does not match the Content-Type or is unparseable + Response 401 (application/json) + Attributes (object) @@ -517,6 +554,15 @@ This operation can only be executed by the owner of an entry as well as moderato A comprehensive list of possible errors: - `ENTRY_DOES_NOT_EXIST` if the entry specified by the URI does not exist in the database ++ Response 406 (application/json) + + Attributes (object) + + status (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `REQUEST_UNSUPPORTED_CONTENT_TYPE` if the submitted Content-Type is not `application/json` + ## Delete an entry [DELETE /database/{organization}/{application}/{scope}/{slug}] From dcb351e387a5f4574a21681f6b7838c14a555d5f Mon Sep 17 00:00:00 2001 From: Namoshek Date: Mon, 12 Sep 2016 15:43:04 +0200 Subject: [PATCH 15/54] REST service: api-description updated (new password regex) --- doc/rest_api/snippet_sharing/api-description.apib | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/rest_api/snippet_sharing/api-description.apib b/doc/rest_api/snippet_sharing/api-description.apib index 1d1bc28dcd9..c63deff5e0d 100644 --- a/doc/rest_api/snippet_sharing/api-description.apib +++ b/doc/rest_api/snippet_sharing/api-description.apib @@ -157,7 +157,7 @@ This method can be used to register for the service by creating a new user accou The password must be at least 8 signs long and contain at least one lower-case letter, one upper-case letter and one digit. To harden security, the user is encouraged to use special characters as well. - Regex: ^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[a-zA-Z\d]{8,}$ + Regex: ^(?=.*[a-z])(?=.*[A-Z])(?=.*[0-9]).{8,}$ + email: `an@email.com` (string, required) @@ -182,7 +182,7 @@ This method can be used to register for the service by creating a new user accou - `USER_CREATE_MISSING_PASSWORD` if no input for `password` was submitted - `USER_CREATE_MISSING_EMAIL` if no input for `email` was submitted - `USER_CREATE_INVALID_USERNAME` if the supplied `username` does not match the given criteria (regex: ^[a-zA-Z0-9\-\.]{3,20}$) - - `USER_CREATE_INVALID_PASSWORD` if the supplied `password` does not satisfy the given criteria (regex: ^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[a-zA-Z\d]{8,}$) + - `USER_CREATE_INVALID_PASSWORD` if the supplied `password` does not satisfy the given criteria (regex: ^(?=.*[a-z])(?=.*[A-Z])(?=.*[0-9]).{8,}$) - `USER_CREATE_INVALID_EMAIL` if the supplied `email` is not a valid email - `REQUEST_MALFORMED_DATA` if the submitted data in the request body does not match the Content-Type or is unparseable @@ -222,7 +222,7 @@ This method can be used to edit an user. If no `name` is supplied, the currently The new password for the user. - Regex: ^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[a-zA-Z\d]{8,}$ + Regex: ^(?=.*[a-z])(?=.*[A-Z])(?=.*[0-9]).{8,}$ + rank: `3` (enum[number], optional) @@ -250,7 +250,7 @@ This method can be used to edit an user. If no `name` is supplied, the currently + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: - - `USER_UPDATE_INVALID_PASSWORD` if the supplied `password` does not satisfy the given criteria (regex: ^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[a-zA-Z\d]{8,}$) + - `USER_UPDATE_INVALID_PASSWORD` if the supplied `password` does not satisfy the given criteria (regex: ^(?=.*[a-z])(?=.*[A-Z])(?=.*[0-9]).{8,}$) - `USER_UPDATE_INVALID_EMAIL` if the supplied `email` is not a valid email - `USER_UPDATE_INVALID_RANK` if the supplied `rank` is not a valid rank (regex: ^[1-3]$) - `REQUEST_MALFORMED_DATA` if the submitted data in the request body does not match the Content-Type or is unparseable From af608055368fed7c21eb14fc1a803f1a04f3e40b Mon Sep 17 00:00:00 2001 From: Namoshek Date: Tue, 13 Sep 2016 08:34:54 +0200 Subject: [PATCH 16/54] REST service: api-description updated (changed users endpoint to user endpoint) --- doc/rest_api/snippet_sharing/api-description.apib | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/rest_api/snippet_sharing/api-description.apib b/doc/rest_api/snippet_sharing/api-description.apib index c63deff5e0d..e42b9125d47 100644 --- a/doc/rest_api/snippet_sharing/api-description.apib +++ b/doc/rest_api/snippet_sharing/api-description.apib @@ -80,7 +80,7 @@ The API will try to authenticate the user by the submitted credentials. In case -# Users endpoint [/users{?rows}{?sort}{?sortby}{?filter}{?filterby}{?current}] +# User endpoint [/user{?rows}{?sort}{?sortby}{?filter}{?filterby}{?current}] ## User list [GET] From 9bfa58bc15b29de4cc62c4e688401ecebb82ee16 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Tue, 13 Sep 2016 08:39:11 +0200 Subject: [PATCH 17/54] REST service: api-description updated (changed versioning to use Elektra version) --- doc/rest_api/snippet_sharing/api-description.apib | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/rest_api/snippet_sharing/api-description.apib b/doc/rest_api/snippet_sharing/api-description.apib index e42b9125d47..1dd1627a2a8 100644 --- a/doc/rest_api/snippet_sharing/api-description.apib +++ b/doc/rest_api/snippet_sharing/api-description.apib @@ -16,13 +16,14 @@ Returns an overview of available API methods with required parameters and a desc ## API Version [GET /version] -Returns the currently used version of the API. A version consists of two numbers (format: a.b), where the first number (a) is the major version and the second number (b) the minor version. Minor versions may not contain breaking changes (i.e. backwards-compatibility is ensured), but major versions may. This means that minor versions may only extend the API. +Returns the current version of API and Elektra. For further information see [doc/VERSION.md](https://github.com/ElektraInitiative/libelektra/blob/master/doc/VERSION.md). + Response 200 (application/json) + Attributes (object) + version (string) - The currently used version in its complete format + major (number) - The currently used major version + minor (number) - The currently used minor version + + micro (number) - The currently used micro version From fe7ae56a4437a4d85ebda756035beb28f1e1c3f2 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Tue, 13 Sep 2016 08:41:07 +0200 Subject: [PATCH 18/54] REST service: api-description updated (added offset parameter to user list method) --- doc/rest_api/snippet_sharing/api-description.apib | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/rest_api/snippet_sharing/api-description.apib b/doc/rest_api/snippet_sharing/api-description.apib index 1dd1627a2a8..ed028af67f9 100644 --- a/doc/rest_api/snippet_sharing/api-description.apib +++ b/doc/rest_api/snippet_sharing/api-description.apib @@ -67,7 +67,7 @@ The API will try to authenticate the user by the submitted credentials. In case + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: - - `AUTH_UNKNOWN_USERNAME` if there is no user registered witht he given name + - `AUTH_UNKNOWN_USERNAME` if there is no user registered with the given name - `AUTH_INVALID_PASSWORD` if the given password does not match the password saved for the given account + Response 406 (application/json) @@ -88,6 +88,8 @@ The API will try to authenticate the user by the submitted credentials. In case Retrieves a list of users. The result can be adjusted by additional, but optional parameters. This operation requires moderator permissions (rank 2) or higher. + Parameters + + offset (number, optional) - How many entries to skip for the output, can be used for pagination. + + Default: `0` + rows (number, optional) - How many entries will be added to the output at max. + Default: `200` + sort (enum[string], optional) - How to sort the entries for the output. From 0ad67a2e05f784a6cf8e7536b1b67333a41e1ce7 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Tue, 13 Sep 2016 08:51:54 +0200 Subject: [PATCH 19/54] REST service: api-description updated (changed user ranks, substitution for user model) --- .../snippet_sharing/api-description.apib | 44 +++++++++---------- 1 file changed, 21 insertions(+), 23 deletions(-) diff --git a/doc/rest_api/snippet_sharing/api-description.apib b/doc/rest_api/snippet_sharing/api-description.apib index ed028af67f9..7c96bc052b4 100644 --- a/doc/rest_api/snippet_sharing/api-description.apib +++ b/doc/rest_api/snippet_sharing/api-description.apib @@ -41,7 +41,7 @@ The API will try to authenticate the user by the submitted credentials. In case Regex: ^[a-zA-Z0-9\-\.]{3,20}$ - + password: `a5ecretP4ssword` (string, required) + + password: `ks_4m3kk4JDal.` (string, required) The corresponding password for the supplied user account. @@ -85,7 +85,7 @@ The API will try to authenticate the user by the submitted credentials. In case ## User list [GET] -Retrieves a list of users. The result can be adjusted by additional, but optional parameters. This operation requires moderator permissions (rank 2) or higher. +Retrieves a list of users. The result can be adjusted by additional, but optional parameters. This operation requires moderator permissions (rank 50) or higher. + Parameters + offset (number, optional) - How many entries to skip for the output, can be used for pagination. @@ -116,7 +116,7 @@ Retrieves a list of users. The result can be adjusted by additional, but optiona ## Retrieve user details [GET /{name}{?current}] -Retrieves the details of the specified user. If the parameter `current` is specified, the currently authenticated user will be chosen as target. Retrieving details of other users requires moderator permissions (rank 2) or higher. +Retrieves the details of the specified user. If the parameter `current` is specified, the currently authenticated user will be chosen as target. Retrieving details of other users requires moderator permissions (rank 50) or higher. + Parameters + current (boolean, optional) - If the currently authenticated users details should be fetched @@ -124,14 +124,7 @@ Retrieves the details of the specified user. If the parameter `current` is speci + name (string, required) - The `username` of the user whose details should be fetched + Response 200 (application/json) - + Attributes (object) - + username (string) - The name of the user - + email (string) - The email of the user - + rank (enum[number]) - The rank of the user (higher means more permissions) - + Members - + `1` - Normal user - + `2` - Moderator - + `3` - Admin + + Attributes (User Preview) + Response 401 (application/json) + Attributes (object) @@ -210,33 +203,33 @@ This method can be used to register for the service by creating a new user accou ## Update user [PUT /{name}] -This method can be used to edit an user. If no `name` is supplied, the currently authenticated user is chosen as target. By using this method it is also possible to change the rank of users. Changing the rank as well as other users in general can only be done by admins (rank 3) though. +This method can be used to edit an user. If no `name` is supplied, the currently authenticated user is chosen as target. By using this method it is also possible to change the rank of users. Changing the rank as well as other users in general can only be done by admins (rank 100) though. + Parameters + name (string, optional) - The `username` of an user which is then taken as target for the operation + Request (application/json) + Attributes (object) - + email: `a-new@email.com` (string, optional) + + email: `some-new-chosen@email.com` (string, optional) The new email address which should be used for the user. It has to be a valid email. - + password: `a_new-secureP4ssw0rd` (string, optional) + + password: `ask23hsDja_231l` (string, optional) The new password for the user. Regex: ^(?=.*[a-z])(?=.*[A-Z])(?=.*[0-9]).{8,}$ - + rank: `3` (enum[number], optional) + + rank: `50` (enum[number], optional) The new rank which should be set for the user. Setting this parameter does only result in a change if the currently authenticated user has the permission to change ranks. - Regex: ^[1-3]$ + Regex: ^(10|50|100)$ + Members - + `1` - Normal user - + `2` - Moderator - + `3` - Admin + + `10` - Normal user + + `50` - Moderator + + `100` - Admin + Response 200 (application/json) + Attributes (object) @@ -255,7 +248,7 @@ This method can be used to edit an user. If no `name` is supplied, the currently A comprehensive list of possible errors: - `USER_UPDATE_INVALID_PASSWORD` if the supplied `password` does not satisfy the given criteria (regex: ^(?=.*[a-z])(?=.*[A-Z])(?=.*[0-9]).{8,}$) - `USER_UPDATE_INVALID_EMAIL` if the supplied `email` is not a valid email - - `USER_UPDATE_INVALID_RANK` if the supplied `rank` is not a valid rank (regex: ^[1-3]$) + - `USER_UPDATE_INVALID_RANK` if the supplied `rank` is not a valid rank (regex: ^(10|50|100)$) - `REQUEST_MALFORMED_DATA` if the submitted data in the request body does not match the Content-Type or is unparseable + Response 401 (application/json) @@ -490,7 +483,7 @@ Can be used to create a new entry in the database. An entry consists of a unique Updates the entry with the specified key (path). All fields will be overridden with the supplied data. If no or empty data is supplied, it will also override the old one (especially important for `tags`). -This operation can only be executed by the owner of an entry as well as moderators (rank 2) or higher. +This operation can only be executed by the owner of an entry as well as moderators (rank 50) or higher. + Parameters + organization (string, required) - The `organization` who built the `application` for which the configuration of the entry is meant @@ -571,7 +564,7 @@ This operation can only be executed by the owner of an entry as well as moderato Deletes an entry from the database. -This operation can only be executed by the owner of an entry as well as moderators (rank 2) or higher. +This operation can only be executed by the owner of an entry as well as moderators (rank 50) or higher. + Parameters + organization (string, required) - The `organization` who built the `application` for which the configuration of the entry is meant @@ -621,7 +614,12 @@ This operation can only be executed by the owner of an entry as well as moderato + username (string) - The users name + email (string) - The users email -+ created_at (number) - A timestamp of the moment when the entry has been created ++ rank (enum[number]) - The users rank (higher means more permissions) + + Members + + `10` - Normal user + + `50` - Moderator + + `100` - Admin ++ created_at (number) - A timestamp of the moment when the user has been created ## Entry List (object) From 73a0f8a76ed2f67c4b136643e983cd46fcfabb6a Mon Sep 17 00:00:00 2001 From: Namoshek Date: Tue, 13 Sep 2016 09:03:11 +0200 Subject: [PATCH 20/54] REST service: api-description updated (user: an -> a, better explanation for entry slugs) --- .../snippet_sharing/api-description.apib | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/doc/rest_api/snippet_sharing/api-description.apib b/doc/rest_api/snippet_sharing/api-description.apib index 7c96bc052b4..ee443e49dca 100644 --- a/doc/rest_api/snippet_sharing/api-description.apib +++ b/doc/rest_api/snippet_sharing/api-description.apib @@ -138,7 +138,7 @@ Retrieves the details of the specified user. If the parameter `current` is speci ## Create user [POST] -This method can be used to register for the service by creating a new user account. An user account will grant access to more functions. +This method can be used to register for the service by creating a new user account. A user account will grant access to more functions. + Request (application/json) + Attributes (object) @@ -203,10 +203,10 @@ This method can be used to register for the service by creating a new user accou ## Update user [PUT /{name}] -This method can be used to edit an user. If no `name` is supplied, the currently authenticated user is chosen as target. By using this method it is also possible to change the rank of users. Changing the rank as well as other users in general can only be done by admins (rank 100) though. +This method can be used to edit a user. If no `name` is supplied, the currently authenticated user is chosen as target. By using this method it is also possible to change the rank of users. Changing the rank as well as other users in general can only be done by admins (rank 100) though. + Parameters - + name (string, optional) - The `username` of an user which is then taken as target for the operation + + name (string, optional) - The `username` of a user which is then taken as target for the operation + Request (application/json) + Attributes (object) @@ -301,7 +301,7 @@ Returns a list of database entries. The result can be adjusted by additional, bu + `organization` - Organization to which the application of the configuration belongs to + `application` - Application for which the configuration is meant + `scope` - Application internal scope - + `slug` - Entry specific unique slug + + `slug` - Entry specific slug + filter (string, optional) - Only entries containing the search string in either their path, title, description, author or tags will be added to the output. + filterby (enum[string], optional) - On what fields the filter should be applied to (i.e. what fields to involve in search) + Default: `all` @@ -325,7 +325,7 @@ Returns detailed information about the entry with the specified key (path). If t + organization (string, required) - The `organization` who built the `application` for which the configuration of the entry is meant + application (string, required) - The `application` to which the configuration of the entry belongs to + scope (string, required) - The `application` specific `scope` to which the configuration of the entry belongs to - + slug (string, required) - The unique identifier of the requested entry + + slug (string, required) - The identifier of the requested entry that is unique within the namespace created by `organization`, `application` and `scope` + raw (string, optional) - If this parameter is supplied, the API will attempt to return the requested configuration snippet in the given `raw` format + Response 200 (application/json) @@ -336,7 +336,7 @@ Returns detailed information about the entry with the specified key (path). If t + organization (string) - The organization of the application to which the snippet belongs to + application (string) - The application to which the snippet belongs to + scope (string) - The application internal scope for the configuration snippet - + slug (string) - The unique identification slug of the entry + + slug (string) - The identifying slug of the entry that is unique within the namespace created by `organization`, `application` and `scope` + meta (object) - Additional information about the entry + title (string) - The descriptive title of the entry + description (string) - The extended description of the entry @@ -393,7 +393,7 @@ Can be used to create a new entry in the database. An entry consists of a unique + slug: `sample-snippet-for-devs` (string, required) - A unique slug that identifies the entry and configuration snippet further. + A unique slug that identifies the entry and configuration snippet further. It only needs to be unique within the namespace created by `organization`, `application` and `scope`. Regex: ^[a-zA-Z0-9\.\-]+$ @@ -489,7 +489,7 @@ This operation can only be executed by the owner of an entry as well as moderato + organization (string, required) - The `organization` who built the `application` for which the configuration of the entry is meant + application (string, required) - The `application` to which the configuration of the entry belongs to + scope (string, required) - The `application` specific `scope` to which the configuration of the entry belongs to - + slug (string, required) - The unique identifier of the requested entry + + slug (string, required) - The identifier of the entry that is unique within the namespace created by `organization`, `application` and `scope` + Request (application/json) + Attributes (object) @@ -570,7 +570,7 @@ This operation can only be executed by the owner of an entry as well as moderato + organization (string, required) - The `organization` who built the `application` for which the configuration of the entry is meant + application (string, required) - The `application` to which the configuration of the entry belongs to + scope (string, required) - The `application` specific `scope` to which the configuration of the entry belongs to - + slug (string, required) - The unique identifier of the requested entry + + slug (string, required) - The identifier of the entry that is unique within the namespace created by `organization`, `application` and `scope` + Response 200 (application/json) + Attributes (object) From 1d2c4b92405adf6e7555c2b751252f59bccac43b Mon Sep 17 00:00:00 2001 From: Namoshek Date: Tue, 13 Sep 2016 09:05:24 +0200 Subject: [PATCH 21/54] REST service: api-description updated (fix user endpoint URL) --- doc/rest_api/snippet_sharing/api-description.apib | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/rest_api/snippet_sharing/api-description.apib b/doc/rest_api/snippet_sharing/api-description.apib index ee443e49dca..362cc6b98c8 100644 --- a/doc/rest_api/snippet_sharing/api-description.apib +++ b/doc/rest_api/snippet_sharing/api-description.apib @@ -81,7 +81,7 @@ The API will try to authenticate the user by the submitted credentials. In case -# User endpoint [/user{?rows}{?sort}{?sortby}{?filter}{?filterby}{?current}] +# User endpoint [/user{?offset}{?rows}{?sort}{?sortby}{?filter}{?filterby}{?current}] ## User list [GET] From 76def7267b85946c448b6f9b18e466d1fc6b0974 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Tue, 13 Sep 2016 09:57:38 +0200 Subject: [PATCH 22/54] REST service: api-description updated (add not found errors for user retrival) --- .../snippet_sharing/api-description.apib | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/doc/rest_api/snippet_sharing/api-description.apib b/doc/rest_api/snippet_sharing/api-description.apib index 362cc6b98c8..798958606a3 100644 --- a/doc/rest_api/snippet_sharing/api-description.apib +++ b/doc/rest_api/snippet_sharing/api-description.apib @@ -126,6 +126,15 @@ Retrieves the details of the specified user. If the parameter `current` is speci + Response 200 (application/json) + Attributes (User Preview) ++ Response 400 (application/json) + + Attributes (object) + + status (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `NO_CURRENT_USER` if the user details of the currently authenticated user were requested, but no authentication is active + + Response 401 (application/json) + Attributes (object) + status (string) - Textual description of the HTTP status @@ -134,6 +143,15 @@ Retrieves the details of the specified user. If the parameter `current` is speci A comprehensive list of possible errors: - `NEED_AUTHENTICATION` if no valid session token has been supplied or the user for whom the token has been created does not exist (anymore) + ++ Response 404 (application/json) + + Attributes (object) + + status (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `USER_NOT_FOUND` if the requested user does not exist in the database ## Create user [POST] @@ -261,6 +279,15 @@ This method can be used to edit a user. If no `name` is supplied, the currently - `NEED_AUTHENTICATION` if no valid session token has been supplied or the user for whom the token has been created does not exist (anymore) - `USER_INSUFFICIENT_PERMISSIONS` if the currently authenticated user has insufficient permissions (due to his rank) to perform this action ++ Response 404 (application/json) + + Attributes (object) + + status (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `USER_NOT_FOUND` if the requested user does not exist in the database + + Response 406 (application/json) + Attributes (object) + status (string) - Textual description of the HTTP status From ed1b45129bf040d1d9d81cc08edd74f955256bb6 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Wed, 14 Sep 2016 14:49:48 +0200 Subject: [PATCH 23/54] REST service: use cases --- .../use_cases/UC_authenticate.txt | 18 ++++++++++++++++++ .../use_cases/UC_create_snippet.txt | 17 +++++++++++++++++ .../use_cases/UC_delete_snippet.txt | 17 +++++++++++++++++ .../use_cases/UC_details_snippet.txt | 17 +++++++++++++++++ .../use_cases/UC_download_snippet.txt | 17 +++++++++++++++++ .../use_cases/UC_edit_snippet.txt | 17 +++++++++++++++++ .../snippet_sharing/use_cases/UC_edit_user.txt | 17 +++++++++++++++++ .../snippet_sharing/use_cases/UC_register.txt | 18 ++++++++++++++++++ .../use_cases/UC_search_snippet.txt | 17 +++++++++++++++++ .../use_cases/UC_search_user.txt | 17 +++++++++++++++++ 10 files changed, 172 insertions(+) create mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_authenticate.txt create mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_create_snippet.txt create mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_delete_snippet.txt create mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_details_snippet.txt create mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_download_snippet.txt create mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_edit_snippet.txt create mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_edit_user.txt create mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_register.txt create mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_search_snippet.txt create mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_search_user.txt diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_authenticate.txt b/doc/rest_api/snippet_sharing/use_cases/UC_authenticate.txt new file mode 100755 index 00000000000..71362e38f5a --- /dev/null +++ b/doc/rest_api/snippet_sharing/use_cases/UC_authenticate.txt @@ -0,0 +1,18 @@ +Summary: +---------------------------- +Title: authenticate +Scope: Authentication +Level: User Goal +Actors: Anonymous User +Brief: Any not logged in user can authenticate to the service. + +Scenarios: +---------------------------- +Precondition: +Main success scenario: User successfully authenticates against the server. Server responds with a session token that is used for authentication in further requests. +Alternative scenario: The authentication was not successful (e.g. wrong credentials) and the server responds with an error. +Error scenario: Technical problems prevent the authentication from succeeding (e.g. connection issues). The user is informed through an error response. +Postcondition: Service is in authenticated state, meaning that all subsequent requests will use the authentication token to identify to the server. +Non-functional Constraints: + - Security mechanism + - Is precondition to use other functions diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_create_snippet.txt b/doc/rest_api/snippet_sharing/use_cases/UC_create_snippet.txt new file mode 100755 index 00000000000..9620c4eab19 --- /dev/null +++ b/doc/rest_api/snippet_sharing/use_cases/UC_create_snippet.txt @@ -0,0 +1,17 @@ +Summary: +---------------------------- +Title: create configuration snippet +Scope: Entry Management +Level: User Goal +Actors: Authenticated User +Brief: User can create a new database entry based on a set of specified inputs, one of them being a configuration snippet. + +Scenarios: +---------------------------- +Precondition: Authenticated +Main success scenario: All inputs validate and the configuration snippet could be stored in the Elektra database successfully. The user retrieves a success response. +Alternative scenario: Wrong inputs lead to an error message and ask the user to correct them, then he can try again. It is also possible that the supplied configuration snippet is of an unsupported format. In either case the user retrieves a response containing error information. +Error scenario: Technical problems prevent the storage process from completing. The user is informed through an error response. +Postcondition: Configuration snippet is stored in the database successfully and can be found through search. +Non-functional Constraints: + - Essential functionality of the service diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_delete_snippet.txt b/doc/rest_api/snippet_sharing/use_cases/UC_delete_snippet.txt new file mode 100755 index 00000000000..4e2e1468238 --- /dev/null +++ b/doc/rest_api/snippet_sharing/use_cases/UC_delete_snippet.txt @@ -0,0 +1,17 @@ +Summary: +---------------------------- +Title: delete configuration snippet +Scope: Entry Management +Level: User Goal +Actors: Authenticated user, Moderator +Brief: Users can delete their own database entries the same way that moderators can delete any configuration snippet in the database. + +Scenarios: +---------------------------- +Precondition: Authenticated, sufficient permissions +Main success scenario: Configuration snippet has been deleted successfully. A success response is returned. +Alternative scenario: The specified snippet cannot be found (wrong URI) or the user has insufficient permissions to delete it. Either way the user is informed about the error by a response. +Error scenario: Technical problems prevent the deletion process from completing. The user is informed by an error response. +Postcondition: Configuration snippet has been deleted from the database and can neither be found through search, nor be viewed in detail anymore. +Non-functional Constraints: + - Moderative feature diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_details_snippet.txt b/doc/rest_api/snippet_sharing/use_cases/UC_details_snippet.txt new file mode 100755 index 00000000000..e458eb9c1a2 --- /dev/null +++ b/doc/rest_api/snippet_sharing/use_cases/UC_details_snippet.txt @@ -0,0 +1,17 @@ +Summary: +---------------------------- +Title: viel details for specific configuration snippet +Scope: Detailed View +Level: User Goal +Actors: Anonymous User (+ all others) +Brief: Any user can view all details about an entry (configuration snippet). + +Scenarios: +---------------------------- +Preconditions: URI of a snippet entry is known +Main success scenario: User retrieves a response containing all information about the entry, including tags and other meta information like a description, as well as the configuration snippet converted into all supported formats. +Alternative scenario: The requested entry (URI) cannot be found, therefore the server responds with an error. +Error scenario: Technical problems prevent server from responding with detailed information. The user is informed about the issue through an error response. +Postcondition: User retrieves detailed information about a database entry containing a configuration snippet, but the database remains unchanged. +Non-functional Constraints: + - Essential functionality of the program diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_download_snippet.txt b/doc/rest_api/snippet_sharing/use_cases/UC_download_snippet.txt new file mode 100755 index 00000000000..9b93fd8afdd --- /dev/null +++ b/doc/rest_api/snippet_sharing/use_cases/UC_download_snippet.txt @@ -0,0 +1,17 @@ +Summary: +---------------------------- +Title: download configuration snippet in specific format +Scope: Detailed View +Level: User Goal +Actors: Anonymous User (+ all others) +Brief: Any user can download the configuration snippets in various formats (XML, JSON, ini, ...). + +Scenarios: +---------------------------- +Precondition: URI of a snippet entry is known +Main success scenario: User successfully downloads the raw configuration snippet in the selected format. The response output can then be stored directly as configuration file. +Alternative scenario: The specified entry (URI) cannot be found. The user is informed about the error by a response. +Error scenario: Technical problems prevent the operation from completing. The user is informed about the error by a response containing further information. +Postcondition: User retrieves the raw snippet, but the database remains unchanged. +Non-functional Constraints: + - Essential functionality of the program diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_edit_snippet.txt b/doc/rest_api/snippet_sharing/use_cases/UC_edit_snippet.txt new file mode 100755 index 00000000000..0b6ccdbe1df --- /dev/null +++ b/doc/rest_api/snippet_sharing/use_cases/UC_edit_snippet.txt @@ -0,0 +1,17 @@ +Summary: +---------------------------- +Title: edit configuration snippet +Scope: Entry Management +Level: User Goal +Actors: Authenticated user, Moderator +Brief: Users can edit their own database entries the same way that moderators can edit any configuration snippet in the database. + +Scenarios: +---------------------------- +Precondition: Authenticated, sufficient permissions +Main success scenario: Changes to the configuration snippet have been stored to the database successfully. The user is informed about the success through a response from the server. +Alternative scenario: The submitted inputs could not be validated or the entry for which changes are requested cannot be found. The server responds with an error message. +Error scenario: Technical problems prevent the storage process from completing. The user is informed about the issue through an error response. +Postcondition: Changes to the configuration snippet are stored in the database successfully and can be immediately seen in new requests of the snippet. +Non-functional Constraints: + - Moderative feature diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_edit_user.txt b/doc/rest_api/snippet_sharing/use_cases/UC_edit_user.txt new file mode 100755 index 00000000000..18a62c1ad90 --- /dev/null +++ b/doc/rest_api/snippet_sharing/use_cases/UC_edit_user.txt @@ -0,0 +1,17 @@ +Summary: +---------------------------- +Title: edit user +Scope: User Management +Level: User Goal +Actors: Authenticated user, Administrator +Brief: Users can edit their own account information the same way Administrators can do it for them. Administrators can also change permissions of users. + +Scenarios: +---------------------------- +Precondition: Authenticated, sufficient permissions +Main success scenario: Changes to the user account have been stored to the database successfully. The operating user is informed about the success through a response from the server. +Alternative scenario: The submitted inputs could not be validated or the user entry for which changes are requested cannot be found. The server responds with an error message. +Error scenario: Technical problems prevent the storage process from completing. The operating user is informed about the issue through an error response. +Postcondition: Changes to the user account are stored in the database successfully and are from now on valid for further requests (e.g. authentication attempts). +Non-functional Constraints: + - Administrative feature diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_register.txt b/doc/rest_api/snippet_sharing/use_cases/UC_register.txt new file mode 100755 index 00000000000..3d145c80ae9 --- /dev/null +++ b/doc/rest_api/snippet_sharing/use_cases/UC_register.txt @@ -0,0 +1,18 @@ +Summary: +---------------------------- +Title: register +Scope: Authentication +Level: User Goal +Actors: Anonymous User +Brief: Any not logged in user can register a new user account. + +Scenarios: +---------------------------- +Precondition: +Main success scenario: User successfully created a new account. Server responds with success response. +Alternative scenario: The inputs could not be validated (do not match the required constraints). An error response is returned. +Error scenario: Technical problems prevent the registration from succeeding. Therefore an error response is returned. +Postcondition: User is created successfully in the database and the provided credentials can now be used to authenticate against the service. +Non-functional Constraints: + - Security mechanism + - Is precondition to use other functions diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_search_snippet.txt b/doc/rest_api/snippet_sharing/use_cases/UC_search_snippet.txt new file mode 100755 index 00000000000..33c70c44caa --- /dev/null +++ b/doc/rest_api/snippet_sharing/use_cases/UC_search_snippet.txt @@ -0,0 +1,17 @@ +Summary: +---------------------------- +Title: search for configuration snippet +Scope: Search +Level: User Goal +Actors: Anonymous User (+ all others) +Brief: Any user can use the search to lookup configuration snippets. + +Scenarios: +---------------------------- +Precondition: +Main success scenario: User retrieves a response from the server containing a list of search results, fitting the given search parameters. +Alternative scenario: The search did not find any entry matching the given search parameters, which will result in an empty list in the response. +Error scenario: Technical problems prevent the search from succeeding. The user receives a response containing detailed error information. +Postcondition: The information given in the search response can be used to lookup more detailed information of entries. +Non-functional Constraints: + - Essential functionality of the program diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_search_user.txt b/doc/rest_api/snippet_sharing/use_cases/UC_search_user.txt new file mode 100755 index 00000000000..6738144cad8 --- /dev/null +++ b/doc/rest_api/snippet_sharing/use_cases/UC_search_user.txt @@ -0,0 +1,17 @@ +Summary: +---------------------------- +Title: search for users +Scope: Search +Level: User Goal +Actors: Administrators +Brief: Administrators can view and search all registered users. + +Scenarios: +---------------------------- +Precondition: +Main success scenario: Administrator retrieves a response from the server containing a list of search results, fitting the given search parameters. +Alternative scenario: The search did not find any user matching the given search parameters, which will result in an empty list in the response. +Error scenario: Technical problems prevent the search from succeeding. The administrator receives a response containing detailed error information. +Postcondition: +Non-functional Constraints: + - Administrative feature From 68bb9d1e966a6188d470717f469086641c03bc70 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Thu, 15 Sep 2016 09:01:09 +0200 Subject: [PATCH 24/54] REST service: use-cases updated --- doc/rest_api/snippet_sharing/use_cases/UC_create_snippet.txt | 2 +- doc/rest_api/snippet_sharing/use_cases/UC_delete_snippet.txt | 2 +- doc/rest_api/snippet_sharing/use_cases/UC_edit_snippet.txt | 2 +- doc/rest_api/snippet_sharing/use_cases/UC_edit_user.txt | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_create_snippet.txt b/doc/rest_api/snippet_sharing/use_cases/UC_create_snippet.txt index 9620c4eab19..e893caa967b 100755 --- a/doc/rest_api/snippet_sharing/use_cases/UC_create_snippet.txt +++ b/doc/rest_api/snippet_sharing/use_cases/UC_create_snippet.txt @@ -10,7 +10,7 @@ Scenarios: ---------------------------- Precondition: Authenticated Main success scenario: All inputs validate and the configuration snippet could be stored in the Elektra database successfully. The user retrieves a success response. -Alternative scenario: Wrong inputs lead to an error message and ask the user to correct them, then he can try again. It is also possible that the supplied configuration snippet is of an unsupported format. In either case the user retrieves a response containing error information. +Alternative scenario: Wrong inputs lead to an error message and ask the user to correct them, then they can try again. It is also possible that the supplied configuration snippet is of an unsupported format. In either case the user retrieves a response containing error information. Error scenario: Technical problems prevent the storage process from completing. The user is informed through an error response. Postcondition: Configuration snippet is stored in the database successfully and can be found through search. Non-functional Constraints: diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_delete_snippet.txt b/doc/rest_api/snippet_sharing/use_cases/UC_delete_snippet.txt index 4e2e1468238..8d40dd0c074 100755 --- a/doc/rest_api/snippet_sharing/use_cases/UC_delete_snippet.txt +++ b/doc/rest_api/snippet_sharing/use_cases/UC_delete_snippet.txt @@ -4,7 +4,7 @@ Title: delete configuration snippet Scope: Entry Management Level: User Goal Actors: Authenticated user, Moderator -Brief: Users can delete their own database entries the same way that moderators can delete any configuration snippet in the database. +Brief: Users can delete their own database entries. Moderators can also delete configuration snippets of other users. Scenarios: ---------------------------- diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_edit_snippet.txt b/doc/rest_api/snippet_sharing/use_cases/UC_edit_snippet.txt index 0b6ccdbe1df..e4bf287a99d 100755 --- a/doc/rest_api/snippet_sharing/use_cases/UC_edit_snippet.txt +++ b/doc/rest_api/snippet_sharing/use_cases/UC_edit_snippet.txt @@ -4,7 +4,7 @@ Title: edit configuration snippet Scope: Entry Management Level: User Goal Actors: Authenticated user, Moderator -Brief: Users can edit their own database entries the same way that moderators can edit any configuration snippet in the database. +Brief: Users can edit their own database entries. Moderators can edit all configuration snippets in the database, also the ones of other users. Scenarios: ---------------------------- diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_edit_user.txt b/doc/rest_api/snippet_sharing/use_cases/UC_edit_user.txt index 18a62c1ad90..ea3b91fc9ef 100755 --- a/doc/rest_api/snippet_sharing/use_cases/UC_edit_user.txt +++ b/doc/rest_api/snippet_sharing/use_cases/UC_edit_user.txt @@ -4,7 +4,7 @@ Title: edit user Scope: User Management Level: User Goal Actors: Authenticated user, Administrator -Brief: Users can edit their own account information the same way Administrators can do it for them. Administrators can also change permissions of users. +Brief: Users can edit their own account information (e.g. change password). Administrators can change all user accounts in the database. Administrators can also change permissions of users. Scenarios: ---------------------------- From a6782c94e3603ac87bfcb5ccb28cb679503bc8c8 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Thu, 15 Sep 2016 13:31:46 +0200 Subject: [PATCH 25/54] REST service: api-description updated (deletion of users, some error response additions) --- .../snippet_sharing/api-description.apib | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/doc/rest_api/snippet_sharing/api-description.apib b/doc/rest_api/snippet_sharing/api-description.apib index 798958606a3..d103584c4b6 100644 --- a/doc/rest_api/snippet_sharing/api-description.apib +++ b/doc/rest_api/snippet_sharing/api-description.apib @@ -114,6 +114,17 @@ Retrieves a list of users. The result can be adjusted by additional, but optiona + Response 200 (application/json) + Attributes (User List) ++ Response 401 (application/json) + + Attributes (object) + + status (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `NEED_AUTHENTICATION` if no valid session token has been supplied or the user for whom the token has been created does not exist (anymore) + - `USER_INSUFFICIENT_PERMISSIONS` if the currently authenticated user has insufficient permissions (due to his rank) to perform this action + + ## Retrieve user details [GET /{name}{?current}] Retrieves the details of the specified user. If the parameter `current` is specified, the currently authenticated user will be chosen as target. Retrieving details of other users requires moderator permissions (rank 50) or higher. @@ -143,6 +154,7 @@ Retrieves the details of the specified user. If the parameter `current` is speci A comprehensive list of possible errors: - `NEED_AUTHENTICATION` if no valid session token has been supplied or the user for whom the token has been created does not exist (anymore) + - `USER_INSUFFICIENT_PERMISSIONS` if the currently authenticated user has insufficient permissions (due to his rank) to perform this action + Response 404 (application/json) + Attributes (object) @@ -298,6 +310,41 @@ This method can be used to edit a user. If no `name` is supplied, the currently - `REQUEST_UNSUPPORTED_CONTENT_TYPE` if the submitted Content-Type is not `application/json` +## Delete user [DELETE /{name}] + +This method can be used to delete a user. If no `name` is supplied, the currently authenticated user is chosen as target. Deleting other users is only possible for admins (rank 100) though. + ++ Parameters + + name (string, optional) - The `username` of a user which is then taken as target for the operation + ++ Response 200 (application/json) + + Attributes (object) + + message (string) - Detailed response information, normally success message + + i18n (string) - A unique token representing above message; can be used for internationalization in frontends + + A comprehensive list of possible messages: + - `USER_DELETED_SUCCESSFULLY` if the changes to the user have been stored successfully + ++ Response 401 (application/json) + + Attributes (object) + + status (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `NEED_AUTHENTICATION` if no valid session token has been supplied or the user for whom the token has been created does not exist (anymore) + - `USER_INSUFFICIENT_PERMISSIONS` if the currently authenticated user has insufficient permissions (due to his rank) to perform this action + ++ Response 404 (application/json) + + Attributes (object) + + status (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `USER_NOT_FOUND` if the requested user does not exist in the database + + # Database endpoint [/database{?offset}{?rows}{?sort}{?sortby}{?filter}{?filterby}{?raw}] From 61837d10f73da508fee9b71bfca9e9dfcdde8178 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Fri, 16 Sep 2016 17:07:00 +0200 Subject: [PATCH 26/54] REST service: use-cases updated (markdown, perspective changed to web gui, added new use cases) --- .../use_cases/UC_authenticate.txt | 24 +++++++++-------- .../use_cases/UC_create_snippet.txt | 24 +++++++++-------- .../use_cases/UC_delete_snippet.txt | 22 +++++++++------- .../use_cases/UC_details_snippet.txt | 26 ++++++++++--------- .../use_cases/UC_download_snippet.txt | 26 ++++++++++--------- .../use_cases/UC_duplicate_snippet.txt | 19 ++++++++++++++ .../use_cases/UC_edit_snippet.txt | 20 +++++++------- .../use_cases/UC_edit_user.txt | 18 +++++++------ .../snippet_sharing/use_cases/UC_register.txt | 22 +++++++++------- .../use_cases/UC_reset_password.txt | 20 ++++++++++++++ .../use_cases/UC_search_snippet.txt | 22 +++++++++------- .../use_cases/UC_search_user.txt | 22 +++++++++------- 12 files changed, 162 insertions(+), 103 deletions(-) create mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_duplicate_snippet.txt create mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_reset_password.txt diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_authenticate.txt b/doc/rest_api/snippet_sharing/use_cases/UC_authenticate.txt index 71362e38f5a..cb3b6c4c3a2 100755 --- a/doc/rest_api/snippet_sharing/use_cases/UC_authenticate.txt +++ b/doc/rest_api/snippet_sharing/use_cases/UC_authenticate.txt @@ -1,18 +1,20 @@ -Summary: ----------------------------- -Title: authenticate +# Use Case: Authenticate + +## Summary + +Title: Authenticate Scope: Authentication Level: User Goal -Actors: Anonymous User +Actors: Anonymous user Brief: Any not logged in user can authenticate to the service. -Scenarios: ----------------------------- -Precondition: -Main success scenario: User successfully authenticates against the server. Server responds with a session token that is used for authentication in further requests. -Alternative scenario: The authentication was not successful (e.g. wrong credentials) and the server responds with an error. -Error scenario: Technical problems prevent the authentication from succeeding (e.g. connection issues). The user is informed through an error response. -Postcondition: Service is in authenticated state, meaning that all subsequent requests will use the authentication token to identify to the server. +## Scenarios + +Precondition: Website opened +Main success scenario: User successfully authenticates against the server. The websites changes its state to authenticated, which enables more features (e.g. creation of snippets). +Alternative scenario: The authentication was not successful (e.g. wrong credentials). The user is prompted to check his credentials and retry. +Error scenario: Technical problems prevent the authentication from succeeding (e.g. connection issues). The user is informed about the issue. +Postcondition: Website is in authenticated state, meaning that all subsequent requests will use the authentication token to identify to the server. Non-functional Constraints: - Security mechanism - Is precondition to use other functions diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_create_snippet.txt b/doc/rest_api/snippet_sharing/use_cases/UC_create_snippet.txt index e893caa967b..6a9de8a85e1 100755 --- a/doc/rest_api/snippet_sharing/use_cases/UC_create_snippet.txt +++ b/doc/rest_api/snippet_sharing/use_cases/UC_create_snippet.txt @@ -1,17 +1,19 @@ -Summary: ----------------------------- -Title: create configuration snippet +# Use Case: Create configuration snippet + +## Summary + +Title: Create configuration snippet Scope: Entry Management Level: User Goal -Actors: Authenticated User -Brief: User can create a new database entry based on a set of specified inputs, one of them being a configuration snippet. +Actors: Authenticated user +Brief: User can create a new configuration snippet (database entry) based on a set of specified inputs, one of them being the snippet itself. + +## Scenarios -Scenarios: ----------------------------- -Precondition: Authenticated -Main success scenario: All inputs validate and the configuration snippet could be stored in the Elektra database successfully. The user retrieves a success response. +Precondition: Authenticated, sufficient permissions +Main success scenario: All inputs validate and the configuration snippet could be parsed and stored in the Elektra database successfully. The user is then redirected to the detailed view of the created snippet. Alternative scenario: Wrong inputs lead to an error message and ask the user to correct them, then they can try again. It is also possible that the supplied configuration snippet is of an unsupported format. In either case the user retrieves a response containing error information. -Error scenario: Technical problems prevent the storage process from completing. The user is informed through an error response. -Postcondition: Configuration snippet is stored in the database successfully and can be found through search. +Error scenario: Technical problems prevent the storage process from completing. The user is informed about the issue. +Postcondition: Configuration snippet is stored in the database successfully and can be found through search and direct link. Non-functional Constraints: - Essential functionality of the service diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_delete_snippet.txt b/doc/rest_api/snippet_sharing/use_cases/UC_delete_snippet.txt index 8d40dd0c074..03480bfa2f1 100755 --- a/doc/rest_api/snippet_sharing/use_cases/UC_delete_snippet.txt +++ b/doc/rest_api/snippet_sharing/use_cases/UC_delete_snippet.txt @@ -1,17 +1,19 @@ -Summary: ----------------------------- -Title: delete configuration snippet +# Use Case: Delete configuration snippet + +## Summary + +Title: Delete configuration snippet Scope: Entry Management Level: User Goal -Actors: Authenticated user, Moderator +Actors: Authenticated user (snippet owner), Moderator Brief: Users can delete their own database entries. Moderators can also delete configuration snippets of other users. -Scenarios: ----------------------------- -Precondition: Authenticated, sufficient permissions -Main success scenario: Configuration snippet has been deleted successfully. A success response is returned. -Alternative scenario: The specified snippet cannot be found (wrong URI) or the user has insufficient permissions to delete it. Either way the user is informed about the error by a response. -Error scenario: Technical problems prevent the deletion process from completing. The user is informed by an error response. +## Scenarios + +Precondition: Authenticated, sufficient permissions, snippet details page opened +Main success scenario: Configuration snippet has been deleted successfully. A success response is returned and the user, if necessary, redirected to the entry overview. +Alternative scenario: The specified snippet cannot be found (wrong URI) or the user has insufficient permissions to delete it. Either way the user is informed about the error by a response and redirected to the overview if necessary. +Error scenario: Technical problems prevent the deletion process from completing. The user is informed about the issue. Postcondition: Configuration snippet has been deleted from the database and can neither be found through search, nor be viewed in detail anymore. Non-functional Constraints: - Moderative feature diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_details_snippet.txt b/doc/rest_api/snippet_sharing/use_cases/UC_details_snippet.txt index e458eb9c1a2..d05674d34dd 100755 --- a/doc/rest_api/snippet_sharing/use_cases/UC_details_snippet.txt +++ b/doc/rest_api/snippet_sharing/use_cases/UC_details_snippet.txt @@ -1,17 +1,19 @@ -Summary: ----------------------------- -Title: viel details for specific configuration snippet -Scope: Detailed View +# Use Case: View details for specific configuration snippet + +## Summary + +Title: View details for specific configuration snippet +Scope: Entry Details Level: User Goal -Actors: Anonymous User (+ all others) +Actors: Anonymous user (+ all others) Brief: Any user can view all details about an entry (configuration snippet). -Scenarios: ----------------------------- -Preconditions: URI of a snippet entry is known -Main success scenario: User retrieves a response containing all information about the entry, including tags and other meta information like a description, as well as the configuration snippet converted into all supported formats. -Alternative scenario: The requested entry (URI) cannot be found, therefore the server responds with an error. -Error scenario: Technical problems prevent server from responding with detailed information. The user is informed about the issue through an error response. -Postcondition: User retrieves detailed information about a database entry containing a configuration snippet, but the database remains unchanged. +## Scenarios + +Preconditions: Snippet has been found through search or URI is known +Main success scenario: User sees detailed information of the requested entry, including tags and other meta information like a description, as well as the configuration snippet converted into all supported formats. +Alternative scenario: The requested entry (URI) cannot be found, therefore the server responds with an error which is displayed to the user. If necessary, the user is redirected to the snippet overview. +Error scenario: Technical problems prevent server from responding with detailed information. The user is informed about the issue. +Postcondition: The database remains unchanged. Non-functional Constraints: - Essential functionality of the program diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_download_snippet.txt b/doc/rest_api/snippet_sharing/use_cases/UC_download_snippet.txt index 9b93fd8afdd..821b63f9eeb 100755 --- a/doc/rest_api/snippet_sharing/use_cases/UC_download_snippet.txt +++ b/doc/rest_api/snippet_sharing/use_cases/UC_download_snippet.txt @@ -1,17 +1,19 @@ -Summary: ----------------------------- -Title: download configuration snippet in specific format -Scope: Detailed View +# Use Case: Download configuration snippet in specific format + +## Summary + +Title: Download configuration snippet in specific format +Scope: Entry Details Level: User Goal -Actors: Anonymous User (+ all others) +Actors: Anonymous user (+ all others) Brief: Any user can download the configuration snippets in various formats (XML, JSON, ini, ...). -Scenarios: ----------------------------- -Precondition: URI of a snippet entry is known -Main success scenario: User successfully downloads the raw configuration snippet in the selected format. The response output can then be stored directly as configuration file. -Alternative scenario: The specified entry (URI) cannot be found. The user is informed about the error by a response. -Error scenario: Technical problems prevent the operation from completing. The user is informed about the error by a response containing further information. -Postcondition: User retrieves the raw snippet, but the database remains unchanged. +## Scenarios + +Precondition: Entry has been found through search or detailed view of an entry is opened +Main success scenario: User successfully downloads the raw configuration snippet in the selected format. The snippet can then be stored directly as configuration file. +Alternative scenario: The specified entry (URI) cannot be found. The user is informed about the error by an error message. +Error scenario: Technical problems prevent the operation from completing. The user is informed about the error by an error message containing further information. +Postcondition: The database remains unchanged. Non-functional Constraints: - Essential functionality of the program diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_duplicate_snippet.txt b/doc/rest_api/snippet_sharing/use_cases/UC_duplicate_snippet.txt new file mode 100755 index 00000000000..1d4c52211f2 --- /dev/null +++ b/doc/rest_api/snippet_sharing/use_cases/UC_duplicate_snippet.txt @@ -0,0 +1,19 @@ +# Use Case: Create configuration snippet from existing snippet + +## Summary + +Title: Create configuration snippet from existing snippet +Scope: Entry Management +Level: User Goal +Actors: Authenticated user +Brief: User can create a new configuration snippet (database entry) based on an existing snippet. The existing snippet will be filled in the mask for the creation of a new snippet. + +## Scenarios + +Precondition: Authenticated, sufficient permissions +Main success scenario: All inputs validate and the configuration snippet could be parsed and stored in the Elektra database successfully. The user is then redirected to the detailed view of the created snippet. +Alternative scenario: Wrong inputs lead to an error message and ask the user to correct them, then they can try again. It is also possible that the supplied configuration snippet is of an unsupported format. In either case the user retrieves a response containing error information. +Error scenario: Technical problems prevent the storage process from completing. The user is informed about the issue. +Postcondition: Configuration snippet is stored in the database successfully and can be found through search and direct link. +Non-functional Constraints: + - Essential functionality of the service diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_edit_snippet.txt b/doc/rest_api/snippet_sharing/use_cases/UC_edit_snippet.txt index e4bf287a99d..303ac5e7250 100755 --- a/doc/rest_api/snippet_sharing/use_cases/UC_edit_snippet.txt +++ b/doc/rest_api/snippet_sharing/use_cases/UC_edit_snippet.txt @@ -1,17 +1,19 @@ -Summary: ----------------------------- -Title: edit configuration snippet +# Use Case: Edit configuration snippet + +## Summary + +Title: Edit configuration snippet Scope: Entry Management Level: User Goal -Actors: Authenticated user, Moderator +Actors: Authenticated user (snippet owner), Moderator Brief: Users can edit their own database entries. Moderators can edit all configuration snippets in the database, also the ones of other users. -Scenarios: ----------------------------- +## Scenarios + Precondition: Authenticated, sufficient permissions -Main success scenario: Changes to the configuration snippet have been stored to the database successfully. The user is informed about the success through a response from the server. -Alternative scenario: The submitted inputs could not be validated or the entry for which changes are requested cannot be found. The server responds with an error message. -Error scenario: Technical problems prevent the storage process from completing. The user is informed about the issue through an error response. +Main success scenario: Changes to the configuration snippet have been stored to the database successfully. The user is informed about the success. +Alternative scenario: The submitted inputs could not be validated or the entry for which changes are requested cannot be found. The user is informed about the error. +Error scenario: Technical problems prevent the storage process from completing. The user is informed about the issue. Postcondition: Changes to the configuration snippet are stored in the database successfully and can be immediately seen in new requests of the snippet. Non-functional Constraints: - Moderative feature diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_edit_user.txt b/doc/rest_api/snippet_sharing/use_cases/UC_edit_user.txt index ea3b91fc9ef..8b4a9c62b05 100755 --- a/doc/rest_api/snippet_sharing/use_cases/UC_edit_user.txt +++ b/doc/rest_api/snippet_sharing/use_cases/UC_edit_user.txt @@ -1,17 +1,19 @@ -Summary: ----------------------------- -Title: edit user +# Use Case: Edit user + +## Summary + +Title: Edit user Scope: User Management Level: User Goal Actors: Authenticated user, Administrator Brief: Users can edit their own account information (e.g. change password). Administrators can change all user accounts in the database. Administrators can also change permissions of users. -Scenarios: ----------------------------- +## Scenarios + Precondition: Authenticated, sufficient permissions -Main success scenario: Changes to the user account have been stored to the database successfully. The operating user is informed about the success through a response from the server. -Alternative scenario: The submitted inputs could not be validated or the user entry for which changes are requested cannot be found. The server responds with an error message. -Error scenario: Technical problems prevent the storage process from completing. The operating user is informed about the issue through an error response. +Main success scenario: Changes to the user account have been stored to the database successfully. The operating user is informed about the success. +Alternative scenario: The submitted inputs could not be validated or the user entry for which changes are requested cannot be found. The user is informed about the error. +Error scenario: Technical problems prevent the storage process from completing. The operating user is informed about the issue. Postcondition: Changes to the user account are stored in the database successfully and are from now on valid for further requests (e.g. authentication attempts). Non-functional Constraints: - Administrative feature diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_register.txt b/doc/rest_api/snippet_sharing/use_cases/UC_register.txt index 3d145c80ae9..d464cb9c055 100755 --- a/doc/rest_api/snippet_sharing/use_cases/UC_register.txt +++ b/doc/rest_api/snippet_sharing/use_cases/UC_register.txt @@ -1,18 +1,20 @@ -Summary: ----------------------------- -Title: register +# Use Case: Register user account + +## Summary + +Title: Register user account Scope: Authentication Level: User Goal -Actors: Anonymous User +Actors: Anonymous user Brief: Any not logged in user can register a new user account. -Scenarios: ----------------------------- +## Scenarios + Precondition: -Main success scenario: User successfully created a new account. Server responds with success response. -Alternative scenario: The inputs could not be validated (do not match the required constraints). An error response is returned. -Error scenario: Technical problems prevent the registration from succeeding. Therefore an error response is returned. -Postcondition: User is created successfully in the database and the provided credentials can now be used to authenticate against the service. +Main success scenario: The user successfully created a new account. The user is informed about the success. +Alternative scenario: The inputs could not be validated (do not match the required constraints). The user is informed about their mistake. +Error scenario: Technical problems prevent the registration from succeeding. The user is informed about the issue. +Postcondition: The user account is created successfully in the database and the provided credentials can now be used to authenticate against the service. Non-functional Constraints: - Security mechanism - Is precondition to use other functions diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_reset_password.txt b/doc/rest_api/snippet_sharing/use_cases/UC_reset_password.txt new file mode 100755 index 00000000000..571c2dbd1e1 --- /dev/null +++ b/doc/rest_api/snippet_sharing/use_cases/UC_reset_password.txt @@ -0,0 +1,20 @@ +# Use Case: Reset password + +## Summary + +Title: Reset password +Scope: Authentication +Level: User Goal +Actors: Anonymous user +Brief: Any not logged in user can reset his password by knowing his username and email address. + +## Scenarios + +Precondition: Website opened +Main success scenario: User successfully resets his password. An email containing the new password will be sent. +Alternative scenario: The entered credentials could not be validated (do not match), which will result in an error being displayed. +Error scenario: Technical problems prevent the password reset from completing. The user is informed about the issue. +Postcondition: User has a newly generated password that they can change after a successful authentication. +Non-functional Constraints: + - Security mechanism + - Recovery mechanism diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_search_snippet.txt b/doc/rest_api/snippet_sharing/use_cases/UC_search_snippet.txt index 33c70c44caa..ba2af60b751 100755 --- a/doc/rest_api/snippet_sharing/use_cases/UC_search_snippet.txt +++ b/doc/rest_api/snippet_sharing/use_cases/UC_search_snippet.txt @@ -1,17 +1,19 @@ -Summary: ----------------------------- -Title: search for configuration snippet +# Use Case: Search for configuration snippets + +## Summary + +Title: Search for configuration snippets Scope: Search Level: User Goal -Actors: Anonymous User (+ all others) +Actors: Anonymous user (+ all others) Brief: Any user can use the search to lookup configuration snippets. -Scenarios: ----------------------------- +## Scenarios + Precondition: -Main success scenario: User retrieves a response from the server containing a list of search results, fitting the given search parameters. -Alternative scenario: The search did not find any entry matching the given search parameters, which will result in an empty list in the response. -Error scenario: Technical problems prevent the search from succeeding. The user receives a response containing detailed error information. -Postcondition: The information given in the search response can be used to lookup more detailed information of entries. +Main success scenario: User is presented a list of possible candidates that match the entered search parameters. +Alternative scenario: The search did not find any entry matching the given search parameters, which will result in an empty list being displayed. +Error scenario: Technical problems prevent the search from succeeding. The user is informed about the issue. +Postcondition: The search results offer additional functionality like downloading of configuration snippets or detailed view. Non-functional Constraints: - Essential functionality of the program diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_search_user.txt b/doc/rest_api/snippet_sharing/use_cases/UC_search_user.txt index 6738144cad8..4985c836c19 100755 --- a/doc/rest_api/snippet_sharing/use_cases/UC_search_user.txt +++ b/doc/rest_api/snippet_sharing/use_cases/UC_search_user.txt @@ -1,17 +1,19 @@ -Summary: ----------------------------- -Title: search for users +# Use Case: Search for users + +## Summary + +Title: Search for users Scope: Search Level: User Goal Actors: Administrators Brief: Administrators can view and search all registered users. -Scenarios: ----------------------------- -Precondition: -Main success scenario: Administrator retrieves a response from the server containing a list of search results, fitting the given search parameters. -Alternative scenario: The search did not find any user matching the given search parameters, which will result in an empty list in the response. -Error scenario: Technical problems prevent the search from succeeding. The administrator receives a response containing detailed error information. -Postcondition: +## Scenarios + +Precondition: Authenticated, sufficient permissions +Main success scenario: Administrator is displayed a list of possible candidates that match the entered search parameters. +Alternative scenario: The search did not find any user matching the given search parameters, which will result in an empty list being displayed. +Error scenario: Technical problems prevent the search from succeeding. The administrator is informed about the issue. +Postcondition: The search results offer additional functionality like editing and deletion of users. Non-functional Constraints: - Administrative feature From 3aa6a0b282ac918fc69b09c18f414ed2180ca0b3 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Mon, 19 Sep 2016 10:18:35 +0200 Subject: [PATCH 27/54] REST service: api-description updated, use cases updated, borders for use cases defined --- .../snippet_sharing/api-description.apib | 96 ++++++++++++++++++- .../use_cases/UC_authenticate.md | 20 ++++ .../use_cases/UC_convert_snippet.md | 19 ++++ .../use_cases/UC_create_snippet.md | 19 ++++ .../use_cases/UC_delete_snippet.md | 19 ++++ .../use_cases/UC_details_snippet.md | 19 ++++ .../use_cases/UC_download_snippet.md | 19 ++++ .../use_cases/UC_duplicate_snippet.md | 19 ++++ .../use_cases/UC_edit_snippet.md | 19 ++++ .../snippet_sharing/use_cases/UC_edit_user.md | 19 ++++ .../snippet_sharing/use_cases/UC_register.md | 20 ++++ .../use_cases/UC_reset_password.md | 20 ++++ .../use_cases/UC_search_snippet.md | 19 ++++ .../use_cases/UC_search_user.md | 19 ++++ .../use_cases/distinction_use_cases.md | 17 ++++ 15 files changed, 359 insertions(+), 4 deletions(-) create mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_authenticate.md create mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_convert_snippet.md create mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_create_snippet.md create mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_delete_snippet.md create mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_details_snippet.md create mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_download_snippet.md create mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_duplicate_snippet.md create mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_edit_snippet.md create mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_edit_user.md create mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_register.md create mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_reset_password.md create mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_search_snippet.md create mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_search_user.md create mode 100644 doc/rest_api/snippet_sharing/use_cases/distinction_use_cases.md diff --git a/doc/rest_api/snippet_sharing/api-description.apib b/doc/rest_api/snippet_sharing/api-description.apib index d103584c4b6..5ffcfd6906e 100644 --- a/doc/rest_api/snippet_sharing/api-description.apib +++ b/doc/rest_api/snippet_sharing/api-description.apib @@ -495,8 +495,8 @@ Can be used to create a new entry in the database. An entry consists of a unique + Response 200 (application/json) + Attributes (object) - + message (string) - Detailed error information, e.g. hint about malformed request - + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + message (string) - Detailed response information, normally success message + + i18n (string) - A unique token representing above message; can be used for internationalization in frontends A comprehensive list of possible messages: - `ENTRY_CREATED_SUCCESSFULLY` if the entry has been added successfully to the database @@ -589,6 +589,14 @@ This operation can only be executed by the owner of an entry as well as moderato The new configuration snippet. It can be of any supported format, in this example **ini** is used. ++ Response 200 (application/json) + + Attributes (object) + + message (string) - Detailed response information, normally success message + + i18n (string) - A unique token representing above message; can be used for internationalization in frontends + + A comprehensive list of possible messages: + - `ENTRY_UPDATED_SUCCESSFULLY` if the entry has been updated successfully + + Response 400 (application/json) + Attributes (object) + status (string) - Textual description of the HTTP status @@ -648,8 +656,8 @@ This operation can only be executed by the owner of an entry as well as moderato + Response 200 (application/json) + Attributes (object) - + message (string) - Detailed error information, e.g. hint about malformed request - + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + message (string) - Detailed response information, normally success message + + i18n (string) - A unique token representing above message; can be used for internationalization in frontends A comprehensive list of possible messages: - `ENTRY_DELETED_SUCCESSFULLY` if the entry has been deleted successfully from the database @@ -672,6 +680,86 @@ This operation can only be executed by the owner of an entry as well as moderato A comprehensive list of possible errors: - `ENTRY_DOES_NOT_EXIST` if the entry specified by the URI does not exist in the database + + + +# Conversion endpoint [/conversion] + +## Convert configuration snippet [POST] + +Offers to convert a supplied configuration snippet from one format into another format. + ++ Request (application/json) + + Attributes (object) + + input (object, required) + + format: `ini` (string, required) + + The configuration format of the input snippet. + + Regex: ^[a-zA-Z0-9\-\.\_]+$ + + + snippet: `some-variable = some special value` (string, required) + + The configuration snippet itself. + + + output (object, required) + + format: `json` (string, required) + + The desired output format. + + Regex: ^[a-zA-Z0-9\-\.\_]+$ + ++ Response 200 (application/json) + + Attributes (object) + + message (string) - Detailed response information, normally success message + + i18n (string) - A unique token representing above message; can be used for internationalization in frontends + + A comprehensive list of possible messages: + - `CONVERT_SUCCESSFUL` if the conversion ran without errors + + + output (object) + + format (string) - The requested output format. + + snippet (string) - The supplied snippet converted into the output format. + ++ Response 400 (application/json) + + Attributes (object) + + status (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `CONVERT_MISSING_INPUT_FORMAT` if no input for `input.format` was submitted + - `CONVERT_MISSING_INPUT_SNIPPET` if no input for `input.snippet` was submitted + - `CONVERT_MISSING_OUTPUT_FORMAT` if no input for `output.format` was submitted + - `CONVERT_INVALID_INPUT_FORMAT` if the submitted `input.format` is malformed (regex: ^[a-zA-Z0-9\-\.\_]+$) + - `CONVERT_INVALID_OUTPUT_FORMAT` if the submitted `output.format` is malformed (regex: ^[a-zA-Z0-9\-\.\_]+$) + - `REQUEST_MALFORMED_DATA` if the submitted data in the request body does not match the Content-Type or is unparseable + ++ Response 406 (application/json) + + Attributes (object) + + status (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `REQUEST_UNSUPPORTED_CONTENT_TYPE` if the submitted Content-Type is not `application/json` + ++ Response 422 (application/json) + + Attributes (object) + + status (string) - Textual description of the HTTP status + + message (string) - Detailed error information, e.g. hint about malformed request + + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends + + A comprehensive list of possible errors: + - `CONVERT_UNABLE_TO_PARSE_SNIPPET` if the submitted `input.snippet` could not be parsed properly + - `CONVERT_UNABLE_TO_CONVERT_SNIPPET` if the submitted `input.snippet` can not be represented using the submitted `output.format` + +## Supported conversion formats [GET /formats] + +Returns a list of supported configuration formats. In general this is a list of formats for which plugins are available and installed. + ++ Response 200 (application/json) + + Attributes (array[string]) diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_authenticate.md b/doc/rest_api/snippet_sharing/use_cases/UC_authenticate.md new file mode 100755 index 00000000000..cb3b6c4c3a2 --- /dev/null +++ b/doc/rest_api/snippet_sharing/use_cases/UC_authenticate.md @@ -0,0 +1,20 @@ +# Use Case: Authenticate + +## Summary + +Title: Authenticate +Scope: Authentication +Level: User Goal +Actors: Anonymous user +Brief: Any not logged in user can authenticate to the service. + +## Scenarios + +Precondition: Website opened +Main success scenario: User successfully authenticates against the server. The websites changes its state to authenticated, which enables more features (e.g. creation of snippets). +Alternative scenario: The authentication was not successful (e.g. wrong credentials). The user is prompted to check his credentials and retry. +Error scenario: Technical problems prevent the authentication from succeeding (e.g. connection issues). The user is informed about the issue. +Postcondition: Website is in authenticated state, meaning that all subsequent requests will use the authentication token to identify to the server. +Non-functional Constraints: + - Security mechanism + - Is precondition to use other functions diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_convert_snippet.md b/doc/rest_api/snippet_sharing/use_cases/UC_convert_snippet.md new file mode 100755 index 00000000000..0f2cf521899 --- /dev/null +++ b/doc/rest_api/snippet_sharing/use_cases/UC_convert_snippet.md @@ -0,0 +1,19 @@ +# Use Case: Convert configuration snippet + +## Summary + +Title: Convert configuration snippet +Scope: Configuration conversion +Level: User Goal +Actors: Anonymous user (+ all others) +Brief: User can input a configuration snippet in any supported format (e.g. ini, xml) and convert it into another supported format (e.g. json). + +## Scenarios + +Precondition: Service supports the in- and output configuration format +Main success scenario: All inputs validate and the configuration snippet could be converted into the target format. The user is then shown the result of the conversion - the input snippet in another format. +Alternative scenario: Wrong inputs lead to an error message and ask the user to correct them, then they can try again. It is also possible that the supplied configuration snippet is of an unsupported format. In either case the user retrieves a response containing error information. +Error scenario: Technical problems prevent the conversion from completing. The user is informed about the issue. +Postcondition: No changes have been made to the database. +Non-functional Constraints: + - Show-case functionality of Elektra diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_create_snippet.md b/doc/rest_api/snippet_sharing/use_cases/UC_create_snippet.md new file mode 100755 index 00000000000..6a9de8a85e1 --- /dev/null +++ b/doc/rest_api/snippet_sharing/use_cases/UC_create_snippet.md @@ -0,0 +1,19 @@ +# Use Case: Create configuration snippet + +## Summary + +Title: Create configuration snippet +Scope: Entry Management +Level: User Goal +Actors: Authenticated user +Brief: User can create a new configuration snippet (database entry) based on a set of specified inputs, one of them being the snippet itself. + +## Scenarios + +Precondition: Authenticated, sufficient permissions +Main success scenario: All inputs validate and the configuration snippet could be parsed and stored in the Elektra database successfully. The user is then redirected to the detailed view of the created snippet. +Alternative scenario: Wrong inputs lead to an error message and ask the user to correct them, then they can try again. It is also possible that the supplied configuration snippet is of an unsupported format. In either case the user retrieves a response containing error information. +Error scenario: Technical problems prevent the storage process from completing. The user is informed about the issue. +Postcondition: Configuration snippet is stored in the database successfully and can be found through search and direct link. +Non-functional Constraints: + - Essential functionality of the service diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_delete_snippet.md b/doc/rest_api/snippet_sharing/use_cases/UC_delete_snippet.md new file mode 100755 index 00000000000..03480bfa2f1 --- /dev/null +++ b/doc/rest_api/snippet_sharing/use_cases/UC_delete_snippet.md @@ -0,0 +1,19 @@ +# Use Case: Delete configuration snippet + +## Summary + +Title: Delete configuration snippet +Scope: Entry Management +Level: User Goal +Actors: Authenticated user (snippet owner), Moderator +Brief: Users can delete their own database entries. Moderators can also delete configuration snippets of other users. + +## Scenarios + +Precondition: Authenticated, sufficient permissions, snippet details page opened +Main success scenario: Configuration snippet has been deleted successfully. A success response is returned and the user, if necessary, redirected to the entry overview. +Alternative scenario: The specified snippet cannot be found (wrong URI) or the user has insufficient permissions to delete it. Either way the user is informed about the error by a response and redirected to the overview if necessary. +Error scenario: Technical problems prevent the deletion process from completing. The user is informed about the issue. +Postcondition: Configuration snippet has been deleted from the database and can neither be found through search, nor be viewed in detail anymore. +Non-functional Constraints: + - Moderative feature diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_details_snippet.md b/doc/rest_api/snippet_sharing/use_cases/UC_details_snippet.md new file mode 100755 index 00000000000..d05674d34dd --- /dev/null +++ b/doc/rest_api/snippet_sharing/use_cases/UC_details_snippet.md @@ -0,0 +1,19 @@ +# Use Case: View details for specific configuration snippet + +## Summary + +Title: View details for specific configuration snippet +Scope: Entry Details +Level: User Goal +Actors: Anonymous user (+ all others) +Brief: Any user can view all details about an entry (configuration snippet). + +## Scenarios + +Preconditions: Snippet has been found through search or URI is known +Main success scenario: User sees detailed information of the requested entry, including tags and other meta information like a description, as well as the configuration snippet converted into all supported formats. +Alternative scenario: The requested entry (URI) cannot be found, therefore the server responds with an error which is displayed to the user. If necessary, the user is redirected to the snippet overview. +Error scenario: Technical problems prevent server from responding with detailed information. The user is informed about the issue. +Postcondition: The database remains unchanged. +Non-functional Constraints: + - Essential functionality of the program diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_download_snippet.md b/doc/rest_api/snippet_sharing/use_cases/UC_download_snippet.md new file mode 100755 index 00000000000..821b63f9eeb --- /dev/null +++ b/doc/rest_api/snippet_sharing/use_cases/UC_download_snippet.md @@ -0,0 +1,19 @@ +# Use Case: Download configuration snippet in specific format + +## Summary + +Title: Download configuration snippet in specific format +Scope: Entry Details +Level: User Goal +Actors: Anonymous user (+ all others) +Brief: Any user can download the configuration snippets in various formats (XML, JSON, ini, ...). + +## Scenarios + +Precondition: Entry has been found through search or detailed view of an entry is opened +Main success scenario: User successfully downloads the raw configuration snippet in the selected format. The snippet can then be stored directly as configuration file. +Alternative scenario: The specified entry (URI) cannot be found. The user is informed about the error by an error message. +Error scenario: Technical problems prevent the operation from completing. The user is informed about the error by an error message containing further information. +Postcondition: The database remains unchanged. +Non-functional Constraints: + - Essential functionality of the program diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_duplicate_snippet.md b/doc/rest_api/snippet_sharing/use_cases/UC_duplicate_snippet.md new file mode 100755 index 00000000000..1d4c52211f2 --- /dev/null +++ b/doc/rest_api/snippet_sharing/use_cases/UC_duplicate_snippet.md @@ -0,0 +1,19 @@ +# Use Case: Create configuration snippet from existing snippet + +## Summary + +Title: Create configuration snippet from existing snippet +Scope: Entry Management +Level: User Goal +Actors: Authenticated user +Brief: User can create a new configuration snippet (database entry) based on an existing snippet. The existing snippet will be filled in the mask for the creation of a new snippet. + +## Scenarios + +Precondition: Authenticated, sufficient permissions +Main success scenario: All inputs validate and the configuration snippet could be parsed and stored in the Elektra database successfully. The user is then redirected to the detailed view of the created snippet. +Alternative scenario: Wrong inputs lead to an error message and ask the user to correct them, then they can try again. It is also possible that the supplied configuration snippet is of an unsupported format. In either case the user retrieves a response containing error information. +Error scenario: Technical problems prevent the storage process from completing. The user is informed about the issue. +Postcondition: Configuration snippet is stored in the database successfully and can be found through search and direct link. +Non-functional Constraints: + - Essential functionality of the service diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_edit_snippet.md b/doc/rest_api/snippet_sharing/use_cases/UC_edit_snippet.md new file mode 100755 index 00000000000..303ac5e7250 --- /dev/null +++ b/doc/rest_api/snippet_sharing/use_cases/UC_edit_snippet.md @@ -0,0 +1,19 @@ +# Use Case: Edit configuration snippet + +## Summary + +Title: Edit configuration snippet +Scope: Entry Management +Level: User Goal +Actors: Authenticated user (snippet owner), Moderator +Brief: Users can edit their own database entries. Moderators can edit all configuration snippets in the database, also the ones of other users. + +## Scenarios + +Precondition: Authenticated, sufficient permissions +Main success scenario: Changes to the configuration snippet have been stored to the database successfully. The user is informed about the success. +Alternative scenario: The submitted inputs could not be validated or the entry for which changes are requested cannot be found. The user is informed about the error. +Error scenario: Technical problems prevent the storage process from completing. The user is informed about the issue. +Postcondition: Changes to the configuration snippet are stored in the database successfully and can be immediately seen in new requests of the snippet. +Non-functional Constraints: + - Moderative feature diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_edit_user.md b/doc/rest_api/snippet_sharing/use_cases/UC_edit_user.md new file mode 100755 index 00000000000..8b4a9c62b05 --- /dev/null +++ b/doc/rest_api/snippet_sharing/use_cases/UC_edit_user.md @@ -0,0 +1,19 @@ +# Use Case: Edit user + +## Summary + +Title: Edit user +Scope: User Management +Level: User Goal +Actors: Authenticated user, Administrator +Brief: Users can edit their own account information (e.g. change password). Administrators can change all user accounts in the database. Administrators can also change permissions of users. + +## Scenarios + +Precondition: Authenticated, sufficient permissions +Main success scenario: Changes to the user account have been stored to the database successfully. The operating user is informed about the success. +Alternative scenario: The submitted inputs could not be validated or the user entry for which changes are requested cannot be found. The user is informed about the error. +Error scenario: Technical problems prevent the storage process from completing. The operating user is informed about the issue. +Postcondition: Changes to the user account are stored in the database successfully and are from now on valid for further requests (e.g. authentication attempts). +Non-functional Constraints: + - Administrative feature diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_register.md b/doc/rest_api/snippet_sharing/use_cases/UC_register.md new file mode 100755 index 00000000000..d464cb9c055 --- /dev/null +++ b/doc/rest_api/snippet_sharing/use_cases/UC_register.md @@ -0,0 +1,20 @@ +# Use Case: Register user account + +## Summary + +Title: Register user account +Scope: Authentication +Level: User Goal +Actors: Anonymous user +Brief: Any not logged in user can register a new user account. + +## Scenarios + +Precondition: +Main success scenario: The user successfully created a new account. The user is informed about the success. +Alternative scenario: The inputs could not be validated (do not match the required constraints). The user is informed about their mistake. +Error scenario: Technical problems prevent the registration from succeeding. The user is informed about the issue. +Postcondition: The user account is created successfully in the database and the provided credentials can now be used to authenticate against the service. +Non-functional Constraints: + - Security mechanism + - Is precondition to use other functions diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_reset_password.md b/doc/rest_api/snippet_sharing/use_cases/UC_reset_password.md new file mode 100755 index 00000000000..571c2dbd1e1 --- /dev/null +++ b/doc/rest_api/snippet_sharing/use_cases/UC_reset_password.md @@ -0,0 +1,20 @@ +# Use Case: Reset password + +## Summary + +Title: Reset password +Scope: Authentication +Level: User Goal +Actors: Anonymous user +Brief: Any not logged in user can reset his password by knowing his username and email address. + +## Scenarios + +Precondition: Website opened +Main success scenario: User successfully resets his password. An email containing the new password will be sent. +Alternative scenario: The entered credentials could not be validated (do not match), which will result in an error being displayed. +Error scenario: Technical problems prevent the password reset from completing. The user is informed about the issue. +Postcondition: User has a newly generated password that they can change after a successful authentication. +Non-functional Constraints: + - Security mechanism + - Recovery mechanism diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_search_snippet.md b/doc/rest_api/snippet_sharing/use_cases/UC_search_snippet.md new file mode 100755 index 00000000000..ba2af60b751 --- /dev/null +++ b/doc/rest_api/snippet_sharing/use_cases/UC_search_snippet.md @@ -0,0 +1,19 @@ +# Use Case: Search for configuration snippets + +## Summary + +Title: Search for configuration snippets +Scope: Search +Level: User Goal +Actors: Anonymous user (+ all others) +Brief: Any user can use the search to lookup configuration snippets. + +## Scenarios + +Precondition: +Main success scenario: User is presented a list of possible candidates that match the entered search parameters. +Alternative scenario: The search did not find any entry matching the given search parameters, which will result in an empty list being displayed. +Error scenario: Technical problems prevent the search from succeeding. The user is informed about the issue. +Postcondition: The search results offer additional functionality like downloading of configuration snippets or detailed view. +Non-functional Constraints: + - Essential functionality of the program diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_search_user.md b/doc/rest_api/snippet_sharing/use_cases/UC_search_user.md new file mode 100755 index 00000000000..4985c836c19 --- /dev/null +++ b/doc/rest_api/snippet_sharing/use_cases/UC_search_user.md @@ -0,0 +1,19 @@ +# Use Case: Search for users + +## Summary + +Title: Search for users +Scope: Search +Level: User Goal +Actors: Administrators +Brief: Administrators can view and search all registered users. + +## Scenarios + +Precondition: Authenticated, sufficient permissions +Main success scenario: Administrator is displayed a list of possible candidates that match the entered search parameters. +Alternative scenario: The search did not find any user matching the given search parameters, which will result in an empty list being displayed. +Error scenario: Technical problems prevent the search from succeeding. The administrator is informed about the issue. +Postcondition: The search results offer additional functionality like editing and deletion of users. +Non-functional Constraints: + - Administrative feature diff --git a/doc/rest_api/snippet_sharing/use_cases/distinction_use_cases.md b/doc/rest_api/snippet_sharing/use_cases/distinction_use_cases.md new file mode 100644 index 00000000000..94199eba09a --- /dev/null +++ b/doc/rest_api/snippet_sharing/use_cases/distinction_use_cases.md @@ -0,0 +1,17 @@ +# Distinction of use cases + +## Scoring / Rating [Scope: Search] + +Currently it is not planned to support scoring or rating of snippets. That means it is not possible to retrieve the most viewed, best rated or most often downloaded snippets. + +## Batch manipulation + +It is not planned to support batch manipulation, i.e. editing of several snippets at once or similar actions. If a feature like this will be implemented at some point, then as front-end only feature, resulting in multiple API requests. + +## Snippet conversion + +A feature to convert snippets in between formats will be implemented, although it will not support intermediate transformation via script languages like lua/python. + +## Invalidation of sessions / Logout + +It is not possible to invalidate sessions. This means that although the logout on the front-end is possible, the underlying session would still be active. A stateless server may not store any state information, therefore the session token has to be stored client side. The server has to accept all tokens he gave out for a certain period of time. This is also a known MITM vulnerability that is impossible to fix. From 0ae00f273753f2021161a16ad0abe410b6647824 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Mon, 19 Sep 2016 10:19:11 +0200 Subject: [PATCH 28/54] REST service: technical description, renamed use case files --- .../snippet_sharing/technical_description.md | 27 +++++++++++++++++++ .../use_cases/UC_authenticate.txt | 20 -------------- .../use_cases/UC_create_snippet.txt | 19 ------------- .../use_cases/UC_delete_snippet.txt | 19 ------------- .../use_cases/UC_details_snippet.txt | 19 ------------- .../use_cases/UC_download_snippet.txt | 19 ------------- .../use_cases/UC_duplicate_snippet.txt | 19 ------------- .../use_cases/UC_edit_snippet.txt | 19 ------------- .../use_cases/UC_edit_user.txt | 19 ------------- .../snippet_sharing/use_cases/UC_register.txt | 20 -------------- .../use_cases/UC_reset_password.txt | 20 -------------- .../use_cases/UC_search_snippet.txt | 19 ------------- .../use_cases/UC_search_user.txt | 19 ------------- 13 files changed, 27 insertions(+), 231 deletions(-) create mode 100644 doc/rest_api/snippet_sharing/technical_description.md delete mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_authenticate.txt delete mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_create_snippet.txt delete mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_delete_snippet.txt delete mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_details_snippet.txt delete mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_download_snippet.txt delete mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_duplicate_snippet.txt delete mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_edit_snippet.txt delete mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_edit_user.txt delete mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_register.txt delete mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_reset_password.txt delete mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_search_snippet.txt delete mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_search_user.txt diff --git a/doc/rest_api/snippet_sharing/technical_description.md b/doc/rest_api/snippet_sharing/technical_description.md new file mode 100644 index 00000000000..7806d6804e2 --- /dev/null +++ b/doc/rest_api/snippet_sharing/technical_description.md @@ -0,0 +1,27 @@ +# Technical description + +## REST service + +The REST service will be implemented using [CppCMS](http://cppcms.com/wikipp/en/page/main). A detailed description of the implemented API can be found in the [API description](api-description.apib). The REST service will leave some space for configuration, as not every deployment will look the same. + +## Front-end + +The front-end will be implemented using AngularJS (v1.5), i.e. a SPA (Single Page Application) will be developed. The final SPA will only consist of static files (.html, .js, .css, .jpg, ...), which means that it could be deployed within any web server. To build the SPA from the development resources, [Grunt](http://gruntjs.com/) is used as task runner. + +### Elektra Website + +One part of the front-end will be the new Elektra website containing documentation, tutorials and other important artifacts. If it is possible to display the documentation artifacts without changing their current arrangement (i.e. rename them on GitHub), it would also be easily possible to implement per-version documentation. + +Resources will be fetched directly from GitHub. It is planned to load all content of the website from GitHub, to avoid having to change the front-end itself. The front-end will support Markdown syntax via a plugin like [Showdown](https://github.com/showdownjs/showdown). Styling can then be done easily through CSS. + +#### Example + +An example how the website could look like is the [Laravel website](https://laravel.com/). On the main page the basic idea is presented, whereas the main focus lies on the documentation, which is simply beautiful. + +#### Global search + +It is not planned to implement a global search for the website itself (documentation, tutorials, ...), as the resources come directly from GitHub (but from multiple endpoints). The available search will only search the configuration snippet database. + +#### Website structure + +TBD diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_authenticate.txt b/doc/rest_api/snippet_sharing/use_cases/UC_authenticate.txt deleted file mode 100755 index cb3b6c4c3a2..00000000000 --- a/doc/rest_api/snippet_sharing/use_cases/UC_authenticate.txt +++ /dev/null @@ -1,20 +0,0 @@ -# Use Case: Authenticate - -## Summary - -Title: Authenticate -Scope: Authentication -Level: User Goal -Actors: Anonymous user -Brief: Any not logged in user can authenticate to the service. - -## Scenarios - -Precondition: Website opened -Main success scenario: User successfully authenticates against the server. The websites changes its state to authenticated, which enables more features (e.g. creation of snippets). -Alternative scenario: The authentication was not successful (e.g. wrong credentials). The user is prompted to check his credentials and retry. -Error scenario: Technical problems prevent the authentication from succeeding (e.g. connection issues). The user is informed about the issue. -Postcondition: Website is in authenticated state, meaning that all subsequent requests will use the authentication token to identify to the server. -Non-functional Constraints: - - Security mechanism - - Is precondition to use other functions diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_create_snippet.txt b/doc/rest_api/snippet_sharing/use_cases/UC_create_snippet.txt deleted file mode 100755 index 6a9de8a85e1..00000000000 --- a/doc/rest_api/snippet_sharing/use_cases/UC_create_snippet.txt +++ /dev/null @@ -1,19 +0,0 @@ -# Use Case: Create configuration snippet - -## Summary - -Title: Create configuration snippet -Scope: Entry Management -Level: User Goal -Actors: Authenticated user -Brief: User can create a new configuration snippet (database entry) based on a set of specified inputs, one of them being the snippet itself. - -## Scenarios - -Precondition: Authenticated, sufficient permissions -Main success scenario: All inputs validate and the configuration snippet could be parsed and stored in the Elektra database successfully. The user is then redirected to the detailed view of the created snippet. -Alternative scenario: Wrong inputs lead to an error message and ask the user to correct them, then they can try again. It is also possible that the supplied configuration snippet is of an unsupported format. In either case the user retrieves a response containing error information. -Error scenario: Technical problems prevent the storage process from completing. The user is informed about the issue. -Postcondition: Configuration snippet is stored in the database successfully and can be found through search and direct link. -Non-functional Constraints: - - Essential functionality of the service diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_delete_snippet.txt b/doc/rest_api/snippet_sharing/use_cases/UC_delete_snippet.txt deleted file mode 100755 index 03480bfa2f1..00000000000 --- a/doc/rest_api/snippet_sharing/use_cases/UC_delete_snippet.txt +++ /dev/null @@ -1,19 +0,0 @@ -# Use Case: Delete configuration snippet - -## Summary - -Title: Delete configuration snippet -Scope: Entry Management -Level: User Goal -Actors: Authenticated user (snippet owner), Moderator -Brief: Users can delete their own database entries. Moderators can also delete configuration snippets of other users. - -## Scenarios - -Precondition: Authenticated, sufficient permissions, snippet details page opened -Main success scenario: Configuration snippet has been deleted successfully. A success response is returned and the user, if necessary, redirected to the entry overview. -Alternative scenario: The specified snippet cannot be found (wrong URI) or the user has insufficient permissions to delete it. Either way the user is informed about the error by a response and redirected to the overview if necessary. -Error scenario: Technical problems prevent the deletion process from completing. The user is informed about the issue. -Postcondition: Configuration snippet has been deleted from the database and can neither be found through search, nor be viewed in detail anymore. -Non-functional Constraints: - - Moderative feature diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_details_snippet.txt b/doc/rest_api/snippet_sharing/use_cases/UC_details_snippet.txt deleted file mode 100755 index d05674d34dd..00000000000 --- a/doc/rest_api/snippet_sharing/use_cases/UC_details_snippet.txt +++ /dev/null @@ -1,19 +0,0 @@ -# Use Case: View details for specific configuration snippet - -## Summary - -Title: View details for specific configuration snippet -Scope: Entry Details -Level: User Goal -Actors: Anonymous user (+ all others) -Brief: Any user can view all details about an entry (configuration snippet). - -## Scenarios - -Preconditions: Snippet has been found through search or URI is known -Main success scenario: User sees detailed information of the requested entry, including tags and other meta information like a description, as well as the configuration snippet converted into all supported formats. -Alternative scenario: The requested entry (URI) cannot be found, therefore the server responds with an error which is displayed to the user. If necessary, the user is redirected to the snippet overview. -Error scenario: Technical problems prevent server from responding with detailed information. The user is informed about the issue. -Postcondition: The database remains unchanged. -Non-functional Constraints: - - Essential functionality of the program diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_download_snippet.txt b/doc/rest_api/snippet_sharing/use_cases/UC_download_snippet.txt deleted file mode 100755 index 821b63f9eeb..00000000000 --- a/doc/rest_api/snippet_sharing/use_cases/UC_download_snippet.txt +++ /dev/null @@ -1,19 +0,0 @@ -# Use Case: Download configuration snippet in specific format - -## Summary - -Title: Download configuration snippet in specific format -Scope: Entry Details -Level: User Goal -Actors: Anonymous user (+ all others) -Brief: Any user can download the configuration snippets in various formats (XML, JSON, ini, ...). - -## Scenarios - -Precondition: Entry has been found through search or detailed view of an entry is opened -Main success scenario: User successfully downloads the raw configuration snippet in the selected format. The snippet can then be stored directly as configuration file. -Alternative scenario: The specified entry (URI) cannot be found. The user is informed about the error by an error message. -Error scenario: Technical problems prevent the operation from completing. The user is informed about the error by an error message containing further information. -Postcondition: The database remains unchanged. -Non-functional Constraints: - - Essential functionality of the program diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_duplicate_snippet.txt b/doc/rest_api/snippet_sharing/use_cases/UC_duplicate_snippet.txt deleted file mode 100755 index 1d4c52211f2..00000000000 --- a/doc/rest_api/snippet_sharing/use_cases/UC_duplicate_snippet.txt +++ /dev/null @@ -1,19 +0,0 @@ -# Use Case: Create configuration snippet from existing snippet - -## Summary - -Title: Create configuration snippet from existing snippet -Scope: Entry Management -Level: User Goal -Actors: Authenticated user -Brief: User can create a new configuration snippet (database entry) based on an existing snippet. The existing snippet will be filled in the mask for the creation of a new snippet. - -## Scenarios - -Precondition: Authenticated, sufficient permissions -Main success scenario: All inputs validate and the configuration snippet could be parsed and stored in the Elektra database successfully. The user is then redirected to the detailed view of the created snippet. -Alternative scenario: Wrong inputs lead to an error message and ask the user to correct them, then they can try again. It is also possible that the supplied configuration snippet is of an unsupported format. In either case the user retrieves a response containing error information. -Error scenario: Technical problems prevent the storage process from completing. The user is informed about the issue. -Postcondition: Configuration snippet is stored in the database successfully and can be found through search and direct link. -Non-functional Constraints: - - Essential functionality of the service diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_edit_snippet.txt b/doc/rest_api/snippet_sharing/use_cases/UC_edit_snippet.txt deleted file mode 100755 index 303ac5e7250..00000000000 --- a/doc/rest_api/snippet_sharing/use_cases/UC_edit_snippet.txt +++ /dev/null @@ -1,19 +0,0 @@ -# Use Case: Edit configuration snippet - -## Summary - -Title: Edit configuration snippet -Scope: Entry Management -Level: User Goal -Actors: Authenticated user (snippet owner), Moderator -Brief: Users can edit their own database entries. Moderators can edit all configuration snippets in the database, also the ones of other users. - -## Scenarios - -Precondition: Authenticated, sufficient permissions -Main success scenario: Changes to the configuration snippet have been stored to the database successfully. The user is informed about the success. -Alternative scenario: The submitted inputs could not be validated or the entry for which changes are requested cannot be found. The user is informed about the error. -Error scenario: Technical problems prevent the storage process from completing. The user is informed about the issue. -Postcondition: Changes to the configuration snippet are stored in the database successfully and can be immediately seen in new requests of the snippet. -Non-functional Constraints: - - Moderative feature diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_edit_user.txt b/doc/rest_api/snippet_sharing/use_cases/UC_edit_user.txt deleted file mode 100755 index 8b4a9c62b05..00000000000 --- a/doc/rest_api/snippet_sharing/use_cases/UC_edit_user.txt +++ /dev/null @@ -1,19 +0,0 @@ -# Use Case: Edit user - -## Summary - -Title: Edit user -Scope: User Management -Level: User Goal -Actors: Authenticated user, Administrator -Brief: Users can edit their own account information (e.g. change password). Administrators can change all user accounts in the database. Administrators can also change permissions of users. - -## Scenarios - -Precondition: Authenticated, sufficient permissions -Main success scenario: Changes to the user account have been stored to the database successfully. The operating user is informed about the success. -Alternative scenario: The submitted inputs could not be validated or the user entry for which changes are requested cannot be found. The user is informed about the error. -Error scenario: Technical problems prevent the storage process from completing. The operating user is informed about the issue. -Postcondition: Changes to the user account are stored in the database successfully and are from now on valid for further requests (e.g. authentication attempts). -Non-functional Constraints: - - Administrative feature diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_register.txt b/doc/rest_api/snippet_sharing/use_cases/UC_register.txt deleted file mode 100755 index d464cb9c055..00000000000 --- a/doc/rest_api/snippet_sharing/use_cases/UC_register.txt +++ /dev/null @@ -1,20 +0,0 @@ -# Use Case: Register user account - -## Summary - -Title: Register user account -Scope: Authentication -Level: User Goal -Actors: Anonymous user -Brief: Any not logged in user can register a new user account. - -## Scenarios - -Precondition: -Main success scenario: The user successfully created a new account. The user is informed about the success. -Alternative scenario: The inputs could not be validated (do not match the required constraints). The user is informed about their mistake. -Error scenario: Technical problems prevent the registration from succeeding. The user is informed about the issue. -Postcondition: The user account is created successfully in the database and the provided credentials can now be used to authenticate against the service. -Non-functional Constraints: - - Security mechanism - - Is precondition to use other functions diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_reset_password.txt b/doc/rest_api/snippet_sharing/use_cases/UC_reset_password.txt deleted file mode 100755 index 571c2dbd1e1..00000000000 --- a/doc/rest_api/snippet_sharing/use_cases/UC_reset_password.txt +++ /dev/null @@ -1,20 +0,0 @@ -# Use Case: Reset password - -## Summary - -Title: Reset password -Scope: Authentication -Level: User Goal -Actors: Anonymous user -Brief: Any not logged in user can reset his password by knowing his username and email address. - -## Scenarios - -Precondition: Website opened -Main success scenario: User successfully resets his password. An email containing the new password will be sent. -Alternative scenario: The entered credentials could not be validated (do not match), which will result in an error being displayed. -Error scenario: Technical problems prevent the password reset from completing. The user is informed about the issue. -Postcondition: User has a newly generated password that they can change after a successful authentication. -Non-functional Constraints: - - Security mechanism - - Recovery mechanism diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_search_snippet.txt b/doc/rest_api/snippet_sharing/use_cases/UC_search_snippet.txt deleted file mode 100755 index ba2af60b751..00000000000 --- a/doc/rest_api/snippet_sharing/use_cases/UC_search_snippet.txt +++ /dev/null @@ -1,19 +0,0 @@ -# Use Case: Search for configuration snippets - -## Summary - -Title: Search for configuration snippets -Scope: Search -Level: User Goal -Actors: Anonymous user (+ all others) -Brief: Any user can use the search to lookup configuration snippets. - -## Scenarios - -Precondition: -Main success scenario: User is presented a list of possible candidates that match the entered search parameters. -Alternative scenario: The search did not find any entry matching the given search parameters, which will result in an empty list being displayed. -Error scenario: Technical problems prevent the search from succeeding. The user is informed about the issue. -Postcondition: The search results offer additional functionality like downloading of configuration snippets or detailed view. -Non-functional Constraints: - - Essential functionality of the program diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_search_user.txt b/doc/rest_api/snippet_sharing/use_cases/UC_search_user.txt deleted file mode 100755 index 4985c836c19..00000000000 --- a/doc/rest_api/snippet_sharing/use_cases/UC_search_user.txt +++ /dev/null @@ -1,19 +0,0 @@ -# Use Case: Search for users - -## Summary - -Title: Search for users -Scope: Search -Level: User Goal -Actors: Administrators -Brief: Administrators can view and search all registered users. - -## Scenarios - -Precondition: Authenticated, sufficient permissions -Main success scenario: Administrator is displayed a list of possible candidates that match the entered search parameters. -Alternative scenario: The search did not find any user matching the given search parameters, which will result in an empty list being displayed. -Error scenario: Technical problems prevent the search from succeeding. The administrator is informed about the issue. -Postcondition: The search results offer additional functionality like editing and deletion of users. -Non-functional Constraints: - - Administrative feature From 0d9e811f1dba81dc8675c564fdba76570bf1f2fa Mon Sep 17 00:00:00 2001 From: Namoshek Date: Mon, 19 Sep 2016 10:25:36 +0200 Subject: [PATCH 29/54] REST service: api-description updated (regex for raw format parameter) --- doc/rest_api/snippet_sharing/api-description.apib | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/rest_api/snippet_sharing/api-description.apib b/doc/rest_api/snippet_sharing/api-description.apib index 5ffcfd6906e..5c90da561b1 100644 --- a/doc/rest_api/snippet_sharing/api-description.apib +++ b/doc/rest_api/snippet_sharing/api-description.apib @@ -400,7 +400,7 @@ Returns detailed information about the entry with the specified key (path). If t + application (string, required) - The `application` to which the configuration of the entry belongs to + scope (string, required) - The `application` specific `scope` to which the configuration of the entry belongs to + slug (string, required) - The identifier of the requested entry that is unique within the namespace created by `organization`, `application` and `scope` - + raw (string, optional) - If this parameter is supplied, the API will attempt to return the requested configuration snippet in the given `raw` format + + raw (string, optional) - If this parameter is supplied, the API will attempt to return the requested configuration snippet in the given `raw` format (regex: ^[a-zA-Z0-9\-\.\_]+$) + Response 200 (application/json) + Attributes (object) From 5f02b92d6530cb12cbf2a0459f271ea8aca7a832 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Mon, 19 Sep 2016 10:49:53 +0200 Subject: [PATCH 30/54] REST service: remove UC from PR --- .../snippet_sharing/technical_description.md | 27 ------------------- .../use_cases/UC_authenticate.md | 20 -------------- .../use_cases/UC_convert_snippet.md | 19 ------------- .../use_cases/UC_create_snippet.md | 19 ------------- .../use_cases/UC_delete_snippet.md | 19 ------------- .../use_cases/UC_details_snippet.md | 19 ------------- .../use_cases/UC_download_snippet.md | 19 ------------- .../use_cases/UC_duplicate_snippet.md | 19 ------------- .../use_cases/UC_edit_snippet.md | 19 ------------- .../snippet_sharing/use_cases/UC_edit_user.md | 19 ------------- .../snippet_sharing/use_cases/UC_register.md | 20 -------------- .../use_cases/UC_reset_password.md | 20 -------------- .../use_cases/UC_search_snippet.md | 19 ------------- .../use_cases/UC_search_user.md | 19 ------------- .../use_cases/distinction_use_cases.md | 17 ------------ 15 files changed, 294 deletions(-) delete mode 100644 doc/rest_api/snippet_sharing/technical_description.md delete mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_authenticate.md delete mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_convert_snippet.md delete mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_create_snippet.md delete mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_delete_snippet.md delete mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_details_snippet.md delete mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_download_snippet.md delete mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_duplicate_snippet.md delete mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_edit_snippet.md delete mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_edit_user.md delete mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_register.md delete mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_reset_password.md delete mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_search_snippet.md delete mode 100755 doc/rest_api/snippet_sharing/use_cases/UC_search_user.md delete mode 100644 doc/rest_api/snippet_sharing/use_cases/distinction_use_cases.md diff --git a/doc/rest_api/snippet_sharing/technical_description.md b/doc/rest_api/snippet_sharing/technical_description.md deleted file mode 100644 index 7806d6804e2..00000000000 --- a/doc/rest_api/snippet_sharing/technical_description.md +++ /dev/null @@ -1,27 +0,0 @@ -# Technical description - -## REST service - -The REST service will be implemented using [CppCMS](http://cppcms.com/wikipp/en/page/main). A detailed description of the implemented API can be found in the [API description](api-description.apib). The REST service will leave some space for configuration, as not every deployment will look the same. - -## Front-end - -The front-end will be implemented using AngularJS (v1.5), i.e. a SPA (Single Page Application) will be developed. The final SPA will only consist of static files (.html, .js, .css, .jpg, ...), which means that it could be deployed within any web server. To build the SPA from the development resources, [Grunt](http://gruntjs.com/) is used as task runner. - -### Elektra Website - -One part of the front-end will be the new Elektra website containing documentation, tutorials and other important artifacts. If it is possible to display the documentation artifacts without changing their current arrangement (i.e. rename them on GitHub), it would also be easily possible to implement per-version documentation. - -Resources will be fetched directly from GitHub. It is planned to load all content of the website from GitHub, to avoid having to change the front-end itself. The front-end will support Markdown syntax via a plugin like [Showdown](https://github.com/showdownjs/showdown). Styling can then be done easily through CSS. - -#### Example - -An example how the website could look like is the [Laravel website](https://laravel.com/). On the main page the basic idea is presented, whereas the main focus lies on the documentation, which is simply beautiful. - -#### Global search - -It is not planned to implement a global search for the website itself (documentation, tutorials, ...), as the resources come directly from GitHub (but from multiple endpoints). The available search will only search the configuration snippet database. - -#### Website structure - -TBD diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_authenticate.md b/doc/rest_api/snippet_sharing/use_cases/UC_authenticate.md deleted file mode 100755 index cb3b6c4c3a2..00000000000 --- a/doc/rest_api/snippet_sharing/use_cases/UC_authenticate.md +++ /dev/null @@ -1,20 +0,0 @@ -# Use Case: Authenticate - -## Summary - -Title: Authenticate -Scope: Authentication -Level: User Goal -Actors: Anonymous user -Brief: Any not logged in user can authenticate to the service. - -## Scenarios - -Precondition: Website opened -Main success scenario: User successfully authenticates against the server. The websites changes its state to authenticated, which enables more features (e.g. creation of snippets). -Alternative scenario: The authentication was not successful (e.g. wrong credentials). The user is prompted to check his credentials and retry. -Error scenario: Technical problems prevent the authentication from succeeding (e.g. connection issues). The user is informed about the issue. -Postcondition: Website is in authenticated state, meaning that all subsequent requests will use the authentication token to identify to the server. -Non-functional Constraints: - - Security mechanism - - Is precondition to use other functions diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_convert_snippet.md b/doc/rest_api/snippet_sharing/use_cases/UC_convert_snippet.md deleted file mode 100755 index 0f2cf521899..00000000000 --- a/doc/rest_api/snippet_sharing/use_cases/UC_convert_snippet.md +++ /dev/null @@ -1,19 +0,0 @@ -# Use Case: Convert configuration snippet - -## Summary - -Title: Convert configuration snippet -Scope: Configuration conversion -Level: User Goal -Actors: Anonymous user (+ all others) -Brief: User can input a configuration snippet in any supported format (e.g. ini, xml) and convert it into another supported format (e.g. json). - -## Scenarios - -Precondition: Service supports the in- and output configuration format -Main success scenario: All inputs validate and the configuration snippet could be converted into the target format. The user is then shown the result of the conversion - the input snippet in another format. -Alternative scenario: Wrong inputs lead to an error message and ask the user to correct them, then they can try again. It is also possible that the supplied configuration snippet is of an unsupported format. In either case the user retrieves a response containing error information. -Error scenario: Technical problems prevent the conversion from completing. The user is informed about the issue. -Postcondition: No changes have been made to the database. -Non-functional Constraints: - - Show-case functionality of Elektra diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_create_snippet.md b/doc/rest_api/snippet_sharing/use_cases/UC_create_snippet.md deleted file mode 100755 index 6a9de8a85e1..00000000000 --- a/doc/rest_api/snippet_sharing/use_cases/UC_create_snippet.md +++ /dev/null @@ -1,19 +0,0 @@ -# Use Case: Create configuration snippet - -## Summary - -Title: Create configuration snippet -Scope: Entry Management -Level: User Goal -Actors: Authenticated user -Brief: User can create a new configuration snippet (database entry) based on a set of specified inputs, one of them being the snippet itself. - -## Scenarios - -Precondition: Authenticated, sufficient permissions -Main success scenario: All inputs validate and the configuration snippet could be parsed and stored in the Elektra database successfully. The user is then redirected to the detailed view of the created snippet. -Alternative scenario: Wrong inputs lead to an error message and ask the user to correct them, then they can try again. It is also possible that the supplied configuration snippet is of an unsupported format. In either case the user retrieves a response containing error information. -Error scenario: Technical problems prevent the storage process from completing. The user is informed about the issue. -Postcondition: Configuration snippet is stored in the database successfully and can be found through search and direct link. -Non-functional Constraints: - - Essential functionality of the service diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_delete_snippet.md b/doc/rest_api/snippet_sharing/use_cases/UC_delete_snippet.md deleted file mode 100755 index 03480bfa2f1..00000000000 --- a/doc/rest_api/snippet_sharing/use_cases/UC_delete_snippet.md +++ /dev/null @@ -1,19 +0,0 @@ -# Use Case: Delete configuration snippet - -## Summary - -Title: Delete configuration snippet -Scope: Entry Management -Level: User Goal -Actors: Authenticated user (snippet owner), Moderator -Brief: Users can delete their own database entries. Moderators can also delete configuration snippets of other users. - -## Scenarios - -Precondition: Authenticated, sufficient permissions, snippet details page opened -Main success scenario: Configuration snippet has been deleted successfully. A success response is returned and the user, if necessary, redirected to the entry overview. -Alternative scenario: The specified snippet cannot be found (wrong URI) or the user has insufficient permissions to delete it. Either way the user is informed about the error by a response and redirected to the overview if necessary. -Error scenario: Technical problems prevent the deletion process from completing. The user is informed about the issue. -Postcondition: Configuration snippet has been deleted from the database and can neither be found through search, nor be viewed in detail anymore. -Non-functional Constraints: - - Moderative feature diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_details_snippet.md b/doc/rest_api/snippet_sharing/use_cases/UC_details_snippet.md deleted file mode 100755 index d05674d34dd..00000000000 --- a/doc/rest_api/snippet_sharing/use_cases/UC_details_snippet.md +++ /dev/null @@ -1,19 +0,0 @@ -# Use Case: View details for specific configuration snippet - -## Summary - -Title: View details for specific configuration snippet -Scope: Entry Details -Level: User Goal -Actors: Anonymous user (+ all others) -Brief: Any user can view all details about an entry (configuration snippet). - -## Scenarios - -Preconditions: Snippet has been found through search or URI is known -Main success scenario: User sees detailed information of the requested entry, including tags and other meta information like a description, as well as the configuration snippet converted into all supported formats. -Alternative scenario: The requested entry (URI) cannot be found, therefore the server responds with an error which is displayed to the user. If necessary, the user is redirected to the snippet overview. -Error scenario: Technical problems prevent server from responding with detailed information. The user is informed about the issue. -Postcondition: The database remains unchanged. -Non-functional Constraints: - - Essential functionality of the program diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_download_snippet.md b/doc/rest_api/snippet_sharing/use_cases/UC_download_snippet.md deleted file mode 100755 index 821b63f9eeb..00000000000 --- a/doc/rest_api/snippet_sharing/use_cases/UC_download_snippet.md +++ /dev/null @@ -1,19 +0,0 @@ -# Use Case: Download configuration snippet in specific format - -## Summary - -Title: Download configuration snippet in specific format -Scope: Entry Details -Level: User Goal -Actors: Anonymous user (+ all others) -Brief: Any user can download the configuration snippets in various formats (XML, JSON, ini, ...). - -## Scenarios - -Precondition: Entry has been found through search or detailed view of an entry is opened -Main success scenario: User successfully downloads the raw configuration snippet in the selected format. The snippet can then be stored directly as configuration file. -Alternative scenario: The specified entry (URI) cannot be found. The user is informed about the error by an error message. -Error scenario: Technical problems prevent the operation from completing. The user is informed about the error by an error message containing further information. -Postcondition: The database remains unchanged. -Non-functional Constraints: - - Essential functionality of the program diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_duplicate_snippet.md b/doc/rest_api/snippet_sharing/use_cases/UC_duplicate_snippet.md deleted file mode 100755 index 1d4c52211f2..00000000000 --- a/doc/rest_api/snippet_sharing/use_cases/UC_duplicate_snippet.md +++ /dev/null @@ -1,19 +0,0 @@ -# Use Case: Create configuration snippet from existing snippet - -## Summary - -Title: Create configuration snippet from existing snippet -Scope: Entry Management -Level: User Goal -Actors: Authenticated user -Brief: User can create a new configuration snippet (database entry) based on an existing snippet. The existing snippet will be filled in the mask for the creation of a new snippet. - -## Scenarios - -Precondition: Authenticated, sufficient permissions -Main success scenario: All inputs validate and the configuration snippet could be parsed and stored in the Elektra database successfully. The user is then redirected to the detailed view of the created snippet. -Alternative scenario: Wrong inputs lead to an error message and ask the user to correct them, then they can try again. It is also possible that the supplied configuration snippet is of an unsupported format. In either case the user retrieves a response containing error information. -Error scenario: Technical problems prevent the storage process from completing. The user is informed about the issue. -Postcondition: Configuration snippet is stored in the database successfully and can be found through search and direct link. -Non-functional Constraints: - - Essential functionality of the service diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_edit_snippet.md b/doc/rest_api/snippet_sharing/use_cases/UC_edit_snippet.md deleted file mode 100755 index 303ac5e7250..00000000000 --- a/doc/rest_api/snippet_sharing/use_cases/UC_edit_snippet.md +++ /dev/null @@ -1,19 +0,0 @@ -# Use Case: Edit configuration snippet - -## Summary - -Title: Edit configuration snippet -Scope: Entry Management -Level: User Goal -Actors: Authenticated user (snippet owner), Moderator -Brief: Users can edit their own database entries. Moderators can edit all configuration snippets in the database, also the ones of other users. - -## Scenarios - -Precondition: Authenticated, sufficient permissions -Main success scenario: Changes to the configuration snippet have been stored to the database successfully. The user is informed about the success. -Alternative scenario: The submitted inputs could not be validated or the entry for which changes are requested cannot be found. The user is informed about the error. -Error scenario: Technical problems prevent the storage process from completing. The user is informed about the issue. -Postcondition: Changes to the configuration snippet are stored in the database successfully and can be immediately seen in new requests of the snippet. -Non-functional Constraints: - - Moderative feature diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_edit_user.md b/doc/rest_api/snippet_sharing/use_cases/UC_edit_user.md deleted file mode 100755 index 8b4a9c62b05..00000000000 --- a/doc/rest_api/snippet_sharing/use_cases/UC_edit_user.md +++ /dev/null @@ -1,19 +0,0 @@ -# Use Case: Edit user - -## Summary - -Title: Edit user -Scope: User Management -Level: User Goal -Actors: Authenticated user, Administrator -Brief: Users can edit their own account information (e.g. change password). Administrators can change all user accounts in the database. Administrators can also change permissions of users. - -## Scenarios - -Precondition: Authenticated, sufficient permissions -Main success scenario: Changes to the user account have been stored to the database successfully. The operating user is informed about the success. -Alternative scenario: The submitted inputs could not be validated or the user entry for which changes are requested cannot be found. The user is informed about the error. -Error scenario: Technical problems prevent the storage process from completing. The operating user is informed about the issue. -Postcondition: Changes to the user account are stored in the database successfully and are from now on valid for further requests (e.g. authentication attempts). -Non-functional Constraints: - - Administrative feature diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_register.md b/doc/rest_api/snippet_sharing/use_cases/UC_register.md deleted file mode 100755 index d464cb9c055..00000000000 --- a/doc/rest_api/snippet_sharing/use_cases/UC_register.md +++ /dev/null @@ -1,20 +0,0 @@ -# Use Case: Register user account - -## Summary - -Title: Register user account -Scope: Authentication -Level: User Goal -Actors: Anonymous user -Brief: Any not logged in user can register a new user account. - -## Scenarios - -Precondition: -Main success scenario: The user successfully created a new account. The user is informed about the success. -Alternative scenario: The inputs could not be validated (do not match the required constraints). The user is informed about their mistake. -Error scenario: Technical problems prevent the registration from succeeding. The user is informed about the issue. -Postcondition: The user account is created successfully in the database and the provided credentials can now be used to authenticate against the service. -Non-functional Constraints: - - Security mechanism - - Is precondition to use other functions diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_reset_password.md b/doc/rest_api/snippet_sharing/use_cases/UC_reset_password.md deleted file mode 100755 index 571c2dbd1e1..00000000000 --- a/doc/rest_api/snippet_sharing/use_cases/UC_reset_password.md +++ /dev/null @@ -1,20 +0,0 @@ -# Use Case: Reset password - -## Summary - -Title: Reset password -Scope: Authentication -Level: User Goal -Actors: Anonymous user -Brief: Any not logged in user can reset his password by knowing his username and email address. - -## Scenarios - -Precondition: Website opened -Main success scenario: User successfully resets his password. An email containing the new password will be sent. -Alternative scenario: The entered credentials could not be validated (do not match), which will result in an error being displayed. -Error scenario: Technical problems prevent the password reset from completing. The user is informed about the issue. -Postcondition: User has a newly generated password that they can change after a successful authentication. -Non-functional Constraints: - - Security mechanism - - Recovery mechanism diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_search_snippet.md b/doc/rest_api/snippet_sharing/use_cases/UC_search_snippet.md deleted file mode 100755 index ba2af60b751..00000000000 --- a/doc/rest_api/snippet_sharing/use_cases/UC_search_snippet.md +++ /dev/null @@ -1,19 +0,0 @@ -# Use Case: Search for configuration snippets - -## Summary - -Title: Search for configuration snippets -Scope: Search -Level: User Goal -Actors: Anonymous user (+ all others) -Brief: Any user can use the search to lookup configuration snippets. - -## Scenarios - -Precondition: -Main success scenario: User is presented a list of possible candidates that match the entered search parameters. -Alternative scenario: The search did not find any entry matching the given search parameters, which will result in an empty list being displayed. -Error scenario: Technical problems prevent the search from succeeding. The user is informed about the issue. -Postcondition: The search results offer additional functionality like downloading of configuration snippets or detailed view. -Non-functional Constraints: - - Essential functionality of the program diff --git a/doc/rest_api/snippet_sharing/use_cases/UC_search_user.md b/doc/rest_api/snippet_sharing/use_cases/UC_search_user.md deleted file mode 100755 index 4985c836c19..00000000000 --- a/doc/rest_api/snippet_sharing/use_cases/UC_search_user.md +++ /dev/null @@ -1,19 +0,0 @@ -# Use Case: Search for users - -## Summary - -Title: Search for users -Scope: Search -Level: User Goal -Actors: Administrators -Brief: Administrators can view and search all registered users. - -## Scenarios - -Precondition: Authenticated, sufficient permissions -Main success scenario: Administrator is displayed a list of possible candidates that match the entered search parameters. -Alternative scenario: The search did not find any user matching the given search parameters, which will result in an empty list being displayed. -Error scenario: Technical problems prevent the search from succeeding. The administrator is informed about the issue. -Postcondition: The search results offer additional functionality like editing and deletion of users. -Non-functional Constraints: - - Administrative feature diff --git a/doc/rest_api/snippet_sharing/use_cases/distinction_use_cases.md b/doc/rest_api/snippet_sharing/use_cases/distinction_use_cases.md deleted file mode 100644 index 94199eba09a..00000000000 --- a/doc/rest_api/snippet_sharing/use_cases/distinction_use_cases.md +++ /dev/null @@ -1,17 +0,0 @@ -# Distinction of use cases - -## Scoring / Rating [Scope: Search] - -Currently it is not planned to support scoring or rating of snippets. That means it is not possible to retrieve the most viewed, best rated or most often downloaded snippets. - -## Batch manipulation - -It is not planned to support batch manipulation, i.e. editing of several snippets at once or similar actions. If a feature like this will be implemented at some point, then as front-end only feature, resulting in multiple API requests. - -## Snippet conversion - -A feature to convert snippets in between formats will be implemented, although it will not support intermediate transformation via script languages like lua/python. - -## Invalidation of sessions / Logout - -It is not possible to invalidate sessions. This means that although the logout on the front-end is possible, the underlying session would still be active. A stateless server may not store any state information, therefore the session token has to be stored client side. The server has to accept all tokens he gave out for a certain period of time. This is also a known MITM vulnerability that is impossible to fix. From d2209e19536745e6d22c30733e250832e0699bf6 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Thu, 22 Sep 2016 14:06:07 +0200 Subject: [PATCH 31/54] REST service: api-description path changed --- .../api-description.apib => api_blueprints/snippet-sharing.apib} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename doc/{rest_api/snippet_sharing/api-description.apib => api_blueprints/snippet-sharing.apib} (100%) diff --git a/doc/rest_api/snippet_sharing/api-description.apib b/doc/api_blueprints/snippet-sharing.apib similarity index 100% rename from doc/rest_api/snippet_sharing/api-description.apib rename to doc/api_blueprints/snippet-sharing.apib From 92f6e99ef918e14229d7cf9e841489252afdf662 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Thu, 22 Sep 2016 14:06:41 +0200 Subject: [PATCH 32/54] REST service: api-description format changed --- doc/api_blueprints/snippet-sharing.apib | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api_blueprints/snippet-sharing.apib b/doc/api_blueprints/snippet-sharing.apib index 5c90da561b1..3db9da1dbbc 100644 --- a/doc/api_blueprints/snippet-sharing.apib +++ b/doc/api_blueprints/snippet-sharing.apib @@ -1,4 +1,4 @@ -FORMAT: 1.0 +FORMAT: 1A # REST service API for sharing configuration snippets From cfbc6151c09187bd629da339747ec0bc6b6aa953 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Thu, 22 Sep 2016 14:23:49 +0200 Subject: [PATCH 33/54] REST service: api-description updated (API version) --- doc/api_blueprints/snippet-sharing.apib | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/doc/api_blueprints/snippet-sharing.apib b/doc/api_blueprints/snippet-sharing.apib index 3db9da1dbbc..40c3089fff0 100644 --- a/doc/api_blueprints/snippet-sharing.apib +++ b/doc/api_blueprints/snippet-sharing.apib @@ -16,14 +16,16 @@ Returns an overview of available API methods with required parameters and a desc ## API Version [GET /version] -Returns the current version of API and Elektra. For further information see [doc/VERSION.md](https://github.com/ElektraInitiative/libelektra/blob/master/doc/VERSION.md). +Returns the current version of the API and Elektra. For further information and explanation see [doc/VERSION.md](https://github.com/ElektraInitiative/libelektra/blob/master/doc/VERSION.md). + Response 200 (application/json) + Attributes (object) - + version (string) - The currently used version in its complete format - + major (number) - The currently used major version - + minor (number) - The currently used minor version - + micro (number) - The currently used micro version + + elektra (object) - Detailed version information about the used Elektra library + + version (string) - The currently used version in its complete format + + major (number) - The currently used major version + + minor (number) - The currently used minor version + + micro (number) - The currently used micro version + + api (number) - The version of the API itself From 85cae9a10b807cb48ad383178a0c75b7c5ae65b8 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Sun, 25 Sep 2016 15:00:18 +0200 Subject: [PATCH 34/54] REST service: api-description updated (better explanation of versioning) --- doc/api_blueprints/snippet-sharing.apib | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api_blueprints/snippet-sharing.apib b/doc/api_blueprints/snippet-sharing.apib index 40c3089fff0..9b85f024d40 100644 --- a/doc/api_blueprints/snippet-sharing.apib +++ b/doc/api_blueprints/snippet-sharing.apib @@ -16,7 +16,7 @@ Returns an overview of available API methods with required parameters and a desc ## API Version [GET /version] -Returns the current version of the API and Elektra. For further information and explanation see [doc/VERSION.md](https://github.com/ElektraInitiative/libelektra/blob/master/doc/VERSION.md). +Returns the current version of the API and Elektra. The API version is increased whenever breaking changes (i.e. changes that prevent backward compatibility) are made. The Elektra version is directly taken from the Elektra library, for further information and explanation see [doc/VERSION.md](https://github.com/ElektraInitiative/libelektra/blob/master/doc/VERSION.md). + Response 200 (application/json) + Attributes (object) From 40b15aaf61e1a1fa9b3ad726cf476dffd1820ad4 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Sun, 25 Sep 2016 15:26:21 +0200 Subject: [PATCH 35/54] REST service: api-description updated (host added) --- doc/api_blueprints/snippet-sharing.apib | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/api_blueprints/snippet-sharing.apib b/doc/api_blueprints/snippet-sharing.apib index 9b85f024d40..deb8f6c9a57 100644 --- a/doc/api_blueprints/snippet-sharing.apib +++ b/doc/api_blueprints/snippet-sharing.apib @@ -1,4 +1,5 @@ FORMAT: 1A +HOST: api.libelektra.org # REST service API for sharing configuration snippets From eed184187977951de073b6e1003e53af5a195d95 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Sun, 25 Sep 2016 15:36:57 +0200 Subject: [PATCH 36/54] REST service: api-description updated (added authorization header for some requests) --- doc/api_blueprints/snippet-sharing.apib | 32 +++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/doc/api_blueprints/snippet-sharing.apib b/doc/api_blueprints/snippet-sharing.apib index deb8f6c9a57..0ac23c9c5cc 100644 --- a/doc/api_blueprints/snippet-sharing.apib +++ b/doc/api_blueprints/snippet-sharing.apib @@ -114,6 +114,11 @@ Retrieves a list of users. The result can be adjusted by additional, but optiona + `username` - Only the username + `email` - Only the email ++ Request + + Headers + + Authorization: Bearer + + Response 200 (application/json) + Attributes (User List) @@ -136,6 +141,11 @@ Retrieves the details of the specified user. If the parameter `current` is speci + current (boolean, optional) - If the currently authenticated users details should be fetched + Default: `false` + name (string, required) - The `username` of the user whose details should be fetched + ++ Request + + Headers + + Authorization: Bearer + Response 200 (application/json) + Attributes (User Preview) @@ -242,6 +252,10 @@ This method can be used to edit a user. If no `name` is supplied, the currently + name (string, optional) - The `username` of a user which is then taken as target for the operation + Request (application/json) + + Headers + + Authorization: Bearer + + Attributes (object) + email: `some-new-chosen@email.com` (string, optional) @@ -320,6 +334,11 @@ This method can be used to delete a user. If no `name` is supplied, the currentl + Parameters + name (string, optional) - The `username` of a user which is then taken as target for the operation ++ Request + + Headers + + Authorization: Bearer + + Response 200 (application/json) + Attributes (object) + message (string) - Detailed response information, normally success message @@ -449,6 +468,10 @@ Returns detailed information about the entry with the specified key (path). If t Can be used to create a new entry in the database. An entry consists of a unique key (path) that is built from several individual inputs, a title, description and a configuration snippet in any supported format. + Request (application/json) + + Headers + + Authorization: Bearer + + Attributes (object) + organization: `org.apache` (string, required) @@ -569,6 +592,10 @@ This operation can only be executed by the owner of an entry as well as moderato + slug (string, required) - The identifier of the entry that is unique within the namespace created by `organization`, `application` and `scope` + Request (application/json) + + Headers + + Authorization: Bearer + + Attributes (object) + title: `Sample snippet for developers` (string, required) @@ -657,6 +684,11 @@ This operation can only be executed by the owner of an entry as well as moderato + scope (string, required) - The `application` specific `scope` to which the configuration of the entry belongs to + slug (string, required) - The identifier of the entry that is unique within the namespace created by `organization`, `application` and `scope` ++ Request + + Headers + + Authorization: Bearer + + Response 200 (application/json) + Attributes (object) + message (string) - Detailed response information, normally success message From 0020acf95867c456523bfafb6aa74630d6120054 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Sun, 25 Sep 2016 15:57:47 +0200 Subject: [PATCH 37/54] REST service: api-description updated (configuration format in requests added) --- doc/api_blueprints/snippet-sharing.apib | 34 +++++++++++++++++-------- 1 file changed, 24 insertions(+), 10 deletions(-) diff --git a/doc/api_blueprints/snippet-sharing.apib b/doc/api_blueprints/snippet-sharing.apib index 0ac23c9c5cc..c98935d6cf3 100644 --- a/doc/api_blueprints/snippet-sharing.apib +++ b/doc/api_blueprints/snippet-sharing.apib @@ -515,9 +515,14 @@ Can be used to create a new entry in the database. An entry consists of a unique Regex: ^[a-z0-9\-\.]{3,20}$ - + configuration: `sampleKey = sampleValue` (string, required) - - The configuration for which a new database entry should be created. It can be of any supported format, in this example **ini** is used. + + configuration (object) + + value: `sampleKey = sampleValue` (string, required) + + The configuration for which a new database entry should be created. It can be of any supported format, in this example **ini** is used. + + + format: `ini` (string, required) + + The format of the supplied configuration snippet. It has to be in the list of supported formats, see `/conversion/formats`. + Response 200 (application/json) + Attributes (object) @@ -540,7 +545,8 @@ Can be used to create a new entry in the database. An entry consists of a unique - `ENTRY_MISSING_SLUG` if no input for `slug` was submitted - `ENTRY_MISSING_TITLE` if no input for `title` was submitted - `ENTRY_MISSING_DESCRIPTION` if no input for `description` was submitted - - `ENTRY_MISSING_CONFIGURATION` if no input for `configuration` was submitted + - `ENTRY_MISSING_CONFIGURATION_VALUE` if no input for `configuration.value` was submitted + - `ENTRY_MISSING_CONFIGURATION_FORMAT` if no input for `configuration.format` was submitted - `ENTRY_INVALID_ORGANIZATION` if the submitted `organization` is malformed (regex: ^[a-zA-Z0-9\.\-]+$) - `ENTRY_INVALID_APPLICATION` if the submitted `application` is malformed (regex: ^[a-zA-Z0-9\.\-]+$) - `ENTRY_INVALID_SCOPE` if the submitted `scope` is malformed (regex: ^[a-zA-Z0-9\.\-]+$) @@ -548,7 +554,8 @@ Can be used to create a new entry in the database. An entry consists of a unique - `ENTRY_INVALID_TITLE` if the submitted `title` is malformed (regex: ^[^\n\r]{3,}$) - `ENTRY_INVALID_DESCRIPTION` if the submitted `description` is malformed (regex: ^[\s\S]{3,}$) - `ENTRY_INVALID_TAG` if one of the submitted `tags` is malformed (regex: ^[a-z0-9\-\.]{3,20}$) - - `ENTRY_INVALID_CONFIGURATION` if the submitted configuration snippet has an unsupported format + - `ENTRY_INVALID_CONFIGURATION_VALUE` if the submitted configuration snippet could not be parsed in the submitted format + - `ENTRY_INVALID_CONFIGURATION_FORMAT` if the submitted configuration format is not supported - `REQUEST_MALFORMED_DATA` if the submitted data in the request body does not match the Content-Type or is unparseable + Response 401 (application/json) @@ -615,9 +622,14 @@ This operation can only be executed by the owner of an entry as well as moderato Regex: ^[a-z0-9\-\.]{3,20}$ - + configuration: `sampleKey = sampleValue` (string, required) - - The new configuration snippet. It can be of any supported format, in this example **ini** is used. + + configuration (object) + + value: `sampleKey = sampleValue` (string, required) + + The new configuration snippet. It can be of any supported format, in this example **ini** is used. + + + format: `ini` (string, required) + + The format of the supplied configuration snippet. It has to be in the list of supported formats, see `/conversion/formats`. + Response 200 (application/json) + Attributes (object) @@ -636,11 +648,13 @@ This operation can only be executed by the owner of an entry as well as moderato A comprehensive list of possible errors: - `ENTRY_MISSING_TITLE` if no input for `title` was submitted - `ENTRY_MISSING_DESCRIPTION` if no input for `description` was submitted - - `ENTRY_MISSING_CONFIGURATION` if no input for `configuration` was submitted + - `ENTRY_MISSING_CONFIGURATION_VALUE` if no input for `configuration.value` was submitted + - `ENTRY_MISSING_CONFIGURATION_FORMAT` if no input for `configuration.format` was submitted - `ENTRY_INVALID_TITLE` if the submitted `title` is malformed (regex: ^[^\n\r]{3,}$) - `ENTRY_INVALID_DESCRIPTION` if the submitted `description` is malformed (regex: ^[\s\S]{3,}$) - `ENTRY_INVALID_TAG` if one of the submitted `tags` is malformed (regex: ^[a-z0-9\-\.]{3,20}$) - - `ENTRY_INVALID_CONFIGURATION` if the submitted configuration snippet has an unsupported format + - `ENTRY_INVALID_CONFIGURATION_VALUE` if the submitted configuration snippet could not be parsed in the submitted format + - `ENTRY_INVALID_CONFIGURATION_FORMAT` if the submitted configuration format is not supported - `REQUEST_MALFORMED_DATA` if the submitted data in the request body does not match the Content-Type or is unparseable + Response 401 (application/json) From 7a59b046509e06960007a53519c933046dfb18cd Mon Sep 17 00:00:00 2001 From: Namoshek Date: Mon, 26 Sep 2016 08:35:28 +0200 Subject: [PATCH 38/54] REST service: api-description updated (moved error response to data structure) --- doc/api_blueprints/snippet-sharing.apib | 127 +++++++----------------- 1 file changed, 35 insertions(+), 92 deletions(-) diff --git a/doc/api_blueprints/snippet-sharing.apib b/doc/api_blueprints/snippet-sharing.apib index c98935d6cf3..e91add20c82 100644 --- a/doc/api_blueprints/snippet-sharing.apib +++ b/doc/api_blueprints/snippet-sharing.apib @@ -53,9 +53,7 @@ The API will try to authenticate the user by the submitted credentials. In case + token (string) - The session token which can be used to authenticate against the server in further requests + Response 400 (application/json) - + Attributes (object) - + status (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request + + Attributes (Error Response) + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: @@ -64,9 +62,7 @@ The API will try to authenticate the user by the submitted credentials. In case - `REQUEST_MALFORMED_DATA` if the submitted data in the request body does not match the Content-Type or is unparseable + Response 401 (application/json) - + Attributes (object) - + status (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request + + Attributes (Error Response) + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: @@ -74,9 +70,7 @@ The API will try to authenticate the user by the submitted credentials. In case - `AUTH_INVALID_PASSWORD` if the given password does not match the password saved for the given account + Response 406 (application/json) - + Attributes (object) - + status (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request + + Attributes (Error Response) + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: @@ -123,9 +117,7 @@ Retrieves a list of users. The result can be adjusted by additional, but optiona + Attributes (User List) + Response 401 (application/json) - + Attributes (object) - + status (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request + + Attributes (Error Response) + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: @@ -151,18 +143,14 @@ Retrieves the details of the specified user. If the parameter `current` is speci + Attributes (User Preview) + Response 400 (application/json) - + Attributes (object) - + status (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request + + Attributes (Error Response) + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: - `NO_CURRENT_USER` if the user details of the currently authenticated user were requested, but no authentication is active + Response 401 (application/json) - + Attributes (object) - + status (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request + + Attributes (Error Response) + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: @@ -170,9 +158,7 @@ Retrieves the details of the specified user. If the parameter `current` is speci - `USER_INSUFFICIENT_PERMISSIONS` if the currently authenticated user has insufficient permissions (due to his rank) to perform this action + Response 404 (application/json) - + Attributes (object) - + status (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request + + Attributes (Error Response) + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: @@ -211,9 +197,7 @@ This method can be used to register for the service by creating a new user accou - `USER_CREATED_SUCCESSFULLY` if the account has been created successfully + Response 400 (application/json) - + Attributes (object) - + status (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request + + Attributes (Error Response) + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: @@ -226,18 +210,14 @@ This method can be used to register for the service by creating a new user accou - `REQUEST_MALFORMED_DATA` if the submitted data in the request body does not match the Content-Type or is unparseable + Response 406 (application/json) - + Attributes (object) - + status (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request + + Attributes (Error Response) + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: - `REQUEST_UNSUPPORTED_CONTENT_TYPE` if the submitted Content-Type is not `application/json` + Response 422 (application/json) - + Attributes (object) - + status (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request + + Attributes (Error Response) + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: @@ -287,9 +267,7 @@ This method can be used to edit a user. If no `name` is supplied, the currently - `USER_UPDATED_SUCCESSFULLY` if the changes to the user have been stored successfully + Response 400 (application/json) - + Attributes (object) - + status (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request + + Attributes (Error Response) + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: @@ -299,9 +277,7 @@ This method can be used to edit a user. If no `name` is supplied, the currently - `REQUEST_MALFORMED_DATA` if the submitted data in the request body does not match the Content-Type or is unparseable + Response 401 (application/json) - + Attributes (object) - + status (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request + + Attributes (Error Response) + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: @@ -309,18 +285,14 @@ This method can be used to edit a user. If no `name` is supplied, the currently - `USER_INSUFFICIENT_PERMISSIONS` if the currently authenticated user has insufficient permissions (due to his rank) to perform this action + Response 404 (application/json) - + Attributes (object) - + status (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request + + Attributes (Error Response) + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: - `USER_NOT_FOUND` if the requested user does not exist in the database + Response 406 (application/json) - + Attributes (object) - + status (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request + + Attributes (Error Response) + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: @@ -348,9 +320,7 @@ This method can be used to delete a user. If no `name` is supplied, the currentl - `USER_DELETED_SUCCESSFULLY` if the changes to the user have been stored successfully + Response 401 (application/json) - + Attributes (object) - + status (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request + + Attributes (Error Response) + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: @@ -358,9 +328,7 @@ This method can be used to delete a user. If no `name` is supplied, the currentl - `USER_INSUFFICIENT_PERMISSIONS` if the currently authenticated user has insufficient permissions (due to his rank) to perform this action + Response 404 (application/json) - + Attributes (object) - + status (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request + + Attributes (Error Response) + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: @@ -445,18 +413,14 @@ Returns detailed information about the entry with the specified key (path). If t + Response 200 (text/plain) + Response 400 (application/json) - + Attributes (object) - + status (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request + + Attributes (Error Response) + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: - `ENTRY_UNSUPPORTED_FORMAT` if an unsupported `raw` format has been supplied + Response 404 (application/json) - + Attributes (object) - + status (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request + + Attributes (Error Response) + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: @@ -533,9 +497,7 @@ Can be used to create a new entry in the database. An entry consists of a unique - `ENTRY_CREATED_SUCCESSFULLY` if the entry has been added successfully to the database + Response 400 (application/json) - + Attributes (object) - + status (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request + + Attributes (Error Response) + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: @@ -559,27 +521,21 @@ Can be used to create a new entry in the database. An entry consists of a unique - `REQUEST_MALFORMED_DATA` if the submitted data in the request body does not match the Content-Type or is unparseable + Response 401 (application/json) - + Attributes (object) - + status (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request + + Attributes (Error Response) + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: - `NEED_AUTHENTICATION` if no valid session token has been supplied or the user for whom the token has been created does not exist (anymore) + Response 406 (application/json) - + Attributes (object) - + status (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request + + Attributes (Error Response) + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: - `REQUEST_UNSUPPORTED_CONTENT_TYPE` if the submitted Content-Type is not `application/json` + Response 422 (application/json) - + Attributes (object) - + status (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request + + Attributes (Error Response) + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: @@ -640,9 +596,7 @@ This operation can only be executed by the owner of an entry as well as moderato - `ENTRY_UPDATED_SUCCESSFULLY` if the entry has been updated successfully + Response 400 (application/json) - + Attributes (object) - + status (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request + + Attributes (Error Response) + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: @@ -658,9 +612,7 @@ This operation can only be executed by the owner of an entry as well as moderato - `REQUEST_MALFORMED_DATA` if the submitted data in the request body does not match the Content-Type or is unparseable + Response 401 (application/json) - + Attributes (object) - + status (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request + + Attributes (Error Response) + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: @@ -668,18 +620,14 @@ This operation can only be executed by the owner of an entry as well as moderato - `USER_INSUFFICIENT_PERMISSIONS` if the currently authenticated user has insufficient rights to update the entry (i.e. normal user, but not owner) + Response 404 (application/json) - + Attributes (object) - + status (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request + + Attributes (Error Response) + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: - `ENTRY_DOES_NOT_EXIST` if the entry specified by the URI does not exist in the database + Response 406 (application/json) - + Attributes (object) - + status (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request + + Attributes (Error Response) + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: @@ -712,9 +660,7 @@ This operation can only be executed by the owner of an entry as well as moderato - `ENTRY_DELETED_SUCCESSFULLY` if the entry has been deleted successfully from the database + Response 401 (application/json) - + Attributes (object) - + status (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request + + Attributes (Error Response) + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: @@ -722,9 +668,7 @@ This operation can only be executed by the owner of an entry as well as moderato - `USER_INSUFFICIENT_PERMISSIONS` if the currently authenticated user has insufficient permissions to delete the entry + Response 404 (application/json) - + Attributes (object) - + status (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request + + Attributes (Error Response) + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: @@ -771,9 +715,7 @@ Offers to convert a supplied configuration snippet from one format into another + snippet (string) - The supplied snippet converted into the output format. + Response 400 (application/json) - + Attributes (object) - + status (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request + + Attributes (Error Response) + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: @@ -786,17 +728,13 @@ Offers to convert a supplied configuration snippet from one format into another + Response 406 (application/json) + Attributes (object) - + status (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: - `REQUEST_UNSUPPORTED_CONTENT_TYPE` if the submitted Content-Type is not `application/json` + Response 422 (application/json) - + Attributes (object) - + status (string) - Textual description of the HTTP status - + message (string) - Detailed error information, e.g. hint about malformed request + + Attributes (Error Response) + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: @@ -814,6 +752,11 @@ Returns a list of supported configuration formats. In general this is a list of # Data Structures +## Error Response (object) + ++ status (string) - Textual description of the HTTP status ++ message (string) - Detailed error information, e.g. hint about malformed request + ## User List (object) + elements (number) - How many users the response list contains From 1e5966696bf1d860a66f2012bf24c7ef7dbbd2dd Mon Sep 17 00:00:00 2001 From: Namoshek Date: Mon, 3 Oct 2016 08:47:12 +0200 Subject: [PATCH 39/54] rest-backend: api-description updated (list of supported formats now also contains plugin name) --- doc/api_blueprints/snippet-sharing.apib | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/doc/api_blueprints/snippet-sharing.apib b/doc/api_blueprints/snippet-sharing.apib index e91add20c82..f36c142a6d0 100644 --- a/doc/api_blueprints/snippet-sharing.apib +++ b/doc/api_blueprints/snippet-sharing.apib @@ -746,8 +746,8 @@ Offers to convert a supplied configuration snippet from one format into another Returns a list of supported configuration formats. In general this is a list of formats for which plugins are available and installed. + Response 200 (application/json) - + Attributes (array[string]) - + + Attributes (array[Conversion Format]) + # Data Structures @@ -783,7 +783,6 @@ Returns a list of supported configuration formats. In general this is a list of + remaining (number) - How many entries have not been displayed yet; when adding this value to the offset (and not exceeding the row limit), all entries should have been displayed once + formats (array[string]) - A list of available (enabled) configuration formats; formats in this list can be selected for export - ## Entry Preview (object) + key (string) - Storage path of the entry and also the unique identifier @@ -791,3 +790,8 @@ Returns a list of supported configuration formats. In general this is a list of + description (string) - A description of the entry + author (string) - The username of the creator of the entry + created_at (number) - A timestamp of the moment when the entry has been created + +## Conversion Format (object) + ++ format (string) - The configuration format/language (e.g. ini, xml, csv, ...) ++ plugin (string) - The name of the plugin that offers the format (e.g. simpleini, xmltool, csvstorage, ...) From 712d520bbb53f6ea72f9f0a88db303bffd6fef64 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Mon, 3 Oct 2016 09:26:09 +0200 Subject: [PATCH 40/54] rest-backend: api-description updated (added example values for most request and responses, removed format list from entry list resource, added plugin name to conversion list of entry details) --- doc/api_blueprints/snippet-sharing.apib | 173 +++++++++++++----------- 1 file changed, 91 insertions(+), 82 deletions(-) diff --git a/doc/api_blueprints/snippet-sharing.apib b/doc/api_blueprints/snippet-sharing.apib index f36c142a6d0..aacd227af7d 100644 --- a/doc/api_blueprints/snippet-sharing.apib +++ b/doc/api_blueprints/snippet-sharing.apib @@ -22,11 +22,11 @@ Returns the current version of the API and Elektra. The API version is increased + Response 200 (application/json) + Attributes (object) + elektra (object) - Detailed version information about the used Elektra library - + version (string) - The currently used version in its complete format - + major (number) - The currently used major version - + minor (number) - The currently used minor version - + micro (number) - The currently used micro version - + api (number) - The version of the API itself + + version: `0.8.18` (string) - The currently used version in its complete format + + major: `0` (number) - The currently used major version + + minor: `8` (number) - The currently used minor version + + micro: `18` (number) - The currently used micro version + + api: `1` (number) - The version of the API itself @@ -38,7 +38,7 @@ The API will try to authenticate the user by the submitted credentials. In case + Request (application/json) + Attributes (object) - + username: `the-username` (string, required) + + username: `Namoshek` (string, required) The name of the user account which should be tried to authenticate. @@ -50,7 +50,7 @@ The API will try to authenticate the user by the submitted credentials. In case + Response 200 (application/json) + Attributes (object) - + token (string) - The session token which can be used to authenticate against the server in further requests + + token: `eyJh...1hsbFFGo=` (string) - The session token which can be used to authenticate against the server in further requests + Response 400 (application/json) + Attributes (Error Response) @@ -171,20 +171,20 @@ This method can be used to register for the service by creating a new user accou + Request (application/json) + Attributes (object) - + username: `the_username` (string, required) + + username: `Namoshek` (string, required) The username must be between 3 and 20 signs long and may contain only letters a-z (lower- and upper-case), the numbers 0-9 and dots (.) as well as dashes (-). Regex: ^[a-zA-Z0-9\-\.]{3,20}$ - + password: `somePassword` (string, required) + + password: `eKDaksh382Kda` (string, required) The password must be at least 8 signs long and contain at least one lower-case letter, one upper-case letter and one digit. To harden security, the user is encouraged to use special characters as well. Regex: ^(?=.*[a-z])(?=.*[A-Z])(?=.*[0-9]).{8,}$ - + email: `an@email.com` (string, required) + + email: `some-email@example.com` (string, required) The user has to supply a valid email address. @@ -229,7 +229,7 @@ This method can be used to register for the service by creating a new user accou This method can be used to edit a user. If no `name` is supplied, the currently authenticated user is chosen as target. By using this method it is also possible to change the rank of users. Changing the rank as well as other users in general can only be done by admins (rank 100) though. + Parameters - + name (string, optional) - The `username` of a user which is then taken as target for the operation + + name: `Namoshek` (string, optional) - The `username` of a user which is then taken as target for the operation + Request (application/json) + Headers @@ -237,7 +237,7 @@ This method can be used to edit a user. If no `name` is supplied, the currently Authorization: Bearer + Attributes (object) - + email: `some-new-chosen@email.com` (string, optional) + + email: `some-new-email@example.com` (string, optional) The new email address which should be used for the user. It has to be a valid email. @@ -304,7 +304,7 @@ This method can be used to edit a user. If no `name` is supplied, the currently This method can be used to delete a user. If no `name` is supplied, the currently authenticated user is chosen as target. Deleting other users is only possible for admins (rank 100) though. + Parameters - + name (string, optional) - The `username` of a user which is then taken as target for the operation + + name: `Namoshek` (string, optional) - The `username` of a user which is then taken as target for the operation + Request + Headers @@ -343,12 +343,12 @@ This method can be used to delete a user. If no `name` is supplied, the currentl Returns a list of database entries. The result can be adjusted by additional, but optional parameters. + Parameters - + organization (string, optional) - Only search within a given `organization` for entries - + application (string, optional) - Only search within a given `application` for entries - + scope (string, optional) - Only search within a given `scope` of an `application` for entries - + offset (number, optional) - How many entries to skip for the output, can be used for pagination. + + organization: `apache` (string, optional) - Only search within a given `organization` for entries + + application: `tomcat` (string, optional) - Only search within a given `application` for entries + + scope: `server.xml` (string, optional) - Only search within a given `scope` of an `application` for entries + + offset: `0` (number, optional) - How many entries to skip for the output, can be used for pagination. + Default: `0` - + rows (number, optional) - How many entries will be added to the output at max. + + rows: `1` (number, optional) - How many entries will be added to the output at max. + Default: `200` + sort (enum[string], optional) - How to sort the entries for the output. + Default: `asc` @@ -366,8 +366,8 @@ Returns a list of database entries. The result can be adjusted by additional, bu + `application` - Application for which the configuration is meant + `scope` - Application internal scope + `slug` - Entry specific slug - + filter (string, optional) - Only entries containing the search string in either their path, title, description, author or tags will be added to the output. - + filterby (enum[string], optional) - On what fields the filter should be applied to (i.e. what fields to involve in search) + + filter: `tomcat9` (string, optional) - Only entries containing the search string in either their path, title, description, author or tags will be added to the output. + + filterby: `tags` (enum[string], optional) - On what fields the filter should be applied to (i.e. what fields to involve in search) + Default: `all` + Members + `all` - All fields: key, title, description, author and tags @@ -386,32 +386,36 @@ Returns a list of database entries. The result can be adjusted by additional, bu Returns detailed information about the entry with the specified key (path). If the optional parameter `raw` is supplied, a raw configuration is returned instead of the normal response. + Parameters - + organization (string, required) - The `organization` who built the `application` for which the configuration of the entry is meant - + application (string, required) - The `application` to which the configuration of the entry belongs to - + scope (string, required) - The `application` specific `scope` to which the configuration of the entry belongs to - + slug (string, required) - The identifier of the requested entry that is unique within the namespace created by `organization`, `application` and `scope` - + raw (string, optional) - If this parameter is supplied, the API will attempt to return the requested configuration snippet in the given `raw` format (regex: ^[a-zA-Z0-9\-\.\_]+$) + + organization: `apache` (string, required) - The `organization` who built the `application` for which the configuration of the entry is meant + + application: `tomcat` (string, required) - The `application` to which the configuration of the entry belongs to + + scope: `server.xml` (string, required) - The `application` specific `scope` to which the configuration of the entry belongs to + + slug: `tomcat9-serverxml-example` (string, required) - The identifier of the requested entry that is unique within the namespace created by `organization`, `application` and `scope` + + raw: `xml` (string, optional) - If this parameter is supplied, the API will attempt to return the requested configuration snippet in the given `raw` format (regex: ^[a-zA-Z0-9\-\.\_]+$) + Response 200 (application/json) + Attributes (object) + data (object) - The actual details about the entry + key (object) - The key and its separate parts - + full (string) - The full key (path) of the entry - + organization (string) - The organization of the application to which the snippet belongs to - + application (string) - The application to which the snippet belongs to - + scope (string) - The application internal scope for the configuration snippet - + slug (string) - The identifying slug of the entry that is unique within the namespace created by `organization`, `application` and `scope` + + full: `apache/tomcat/server.xml/tomcat9-serverxml-example` (string) - The full key (path) of the entry + + organization: `apache` (string) - The organization of the application to which the snippet belongs to + + application: `tomcat` (string) - The application to which the snippet belongs to + + scope (string): `server.xml` - The application internal scope for the configuration snippet + + slug (string): `tomcat9-serverxml-example` - The identifying slug of the entry that is unique within the namespace created by `organization`, `application` and `scope` + meta (object) - Additional information about the entry - + title (string) - The descriptive title of the entry - + description (string) - The extended description of the entry - + author (string) - The name of the creator of the entry - + created_at (number) - A timestamp of the creation date of the entry - + value (array[object]) - + format (string) - A configuration format, e.g. **ini** - + value (string) - The configuration snippet in above mentioned format + + title: `Tomcat 9 configuration for server.xml` (string) - The descriptive title of the entry + + description: `The server.xml is Tomcats main configuration file and therefore very important. ...` (string) - The extended description of the entry + + author: `Namoshek` (string) - The name of the creator of the entry + + created_at: `1475478234` (number) - A timestamp of the creation date of the entry + + value (array[Converted Snippet]) + + Response 200 (text/plain) + + + ... + + + Response 400 (application/json) + Attributes (Error Response) + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends @@ -437,54 +441,54 @@ Can be used to create a new entry in the database. An entry consists of a unique Authorization: Bearer + Attributes (object) - + organization: `org.apache` (string, required) + + organization: `apache` (string, required) The organization which built the software for which the configuration is meant. Regex: ^[a-zA-Z0-9\.\-]+$ - + application: `hive` (string, required) + + application: `tomcat` (string, required) The application for which the configuration is meant. Regex: ^[a-zA-Z0-9\.\-]+$ - + scope: `database` (string, required) + + scope: `server.xml` (string, required) Often different parts of an application have different configurations. Here the application specific scope can be defined. Regex: ^[a-zA-Z0-9\.\-]+$ - + slug: `sample-snippet-for-devs` (string, required) + + slug: `tomcat9-serverxml-example` (string, required) A unique slug that identifies the entry and configuration snippet further. It only needs to be unique within the namespace created by `organization`, `application` and `scope`. Regex: ^[a-zA-Z0-9\.\-]+$ - + title: `Sample snippet for developers` (string, required) + + title: `Tomcat 9 configuration for server.xml` (string, required) A title for the entry that ideally explains already what the snippet is about. Regex: ^[^\n\r]{3,}$ - + description: `This is a sample conf snippet for Apaches Hive database module.` (string, required) + + description: `The server.xml is Tomcats main configuration file and therefore very important. ...` (string, required) An extended description for the entry that explains in detail what the snippet is about. It can also contain instructions on how to use the snippet. Regex: ^[\S\s]{3,}$ - + tags: `dev`, `developer`, `db-dev` (array[string], optional) + + tags: `tomcat9`, `tomcat` (array[string], optional) A list of tags that shall be added to the entry. Tags may be used for search, so they ideally add additional information that is not already available by the other inputs. Regex: ^[a-z0-9\-\.]{3,20}$ + configuration (object) - + value: `sampleKey = sampleValue` (string, required) + + value: `...` (string, required) - The configuration for which a new database entry should be created. It can be of any supported format, in this example **ini** is used. + The configuration snippet for which a new database entry should be created. It can be of any supported format. - + format: `ini` (string, required) + + format: `xml` (string, required) The format of the supplied configuration snippet. It has to be in the list of supported formats, see `/conversion/formats`. @@ -549,10 +553,10 @@ Updates the entry with the specified key (path). All fields will be overridden w This operation can only be executed by the owner of an entry as well as moderators (rank 50) or higher. + Parameters - + organization (string, required) - The `organization` who built the `application` for which the configuration of the entry is meant - + application (string, required) - The `application` to which the configuration of the entry belongs to - + scope (string, required) - The `application` specific `scope` to which the configuration of the entry belongs to - + slug (string, required) - The identifier of the entry that is unique within the namespace created by `organization`, `application` and `scope` + + organization: `apache` (string, required) - The `organization` who built the `application` for which the configuration of the entry is meant + + application: `tomcat` (string, required) - The `application` to which the configuration of the entry belongs to + + scope: `server.xml` (string, required) - The `application` specific `scope` to which the configuration of the entry belongs to + + slug: `tomcat9-serverxml-example` (string, required) - The identifier of the entry that is unique within the namespace created by `organization`, `application` and `scope` + Request (application/json) + Headers @@ -560,30 +564,30 @@ This operation can only be executed by the owner of an entry as well as moderato Authorization: Bearer + Attributes (object) - + title: `Sample snippet for developers` (string, required) + + title: `Tomcat 9 configuration for server.xml` (string, required) A title for the entry that ideally explains already what the snippet is about. Regex: ^[^\n\r]{3,}$ - + description: `This is a sample conf snippet for Apaches Hive database module.` (string, required) + + description: `The server.xml is Tomcats main configuration file and therefore very important. ...` (string, required) An extended description for the entry that explains in detail what the snippet is about. It can also contain instructions on how to use the snippet. Regex: ^[\S\s]{3,}$ - + tags: `dev`, `developer`, `db-dev` (array[string], optional) + + tags: `tomcat`, `tomcat9` (array[string], optional) - A list of tags that shall be added to the entry. Tags may be used for search, so they ideally add additional information that is not already available by the other inputs. + A list of tags that shall be added to the entry. Tags may be used for search, so they ideally add additional information that is not already available by the other inputs. The existing tag list will be overriden by the new list, i.e. previously used, but now missing tags will be removed. Regex: ^[a-z0-9\-\.]{3,20}$ + configuration (object) - + value: `sampleKey = sampleValue` (string, required) + + value: `...` (string, required) - The new configuration snippet. It can be of any supported format, in this example **ini** is used. + The new configuration snippet. It can be of any supported format. - + format: `ini` (string, required) + + format: `xml` (string, required) The format of the supplied configuration snippet. It has to be in the list of supported formats, see `/conversion/formats`. @@ -641,10 +645,10 @@ Deletes an entry from the database. This operation can only be executed by the owner of an entry as well as moderators (rank 50) or higher. + Parameters - + organization (string, required) - The `organization` who built the `application` for which the configuration of the entry is meant - + application (string, required) - The `application` to which the configuration of the entry belongs to - + scope (string, required) - The `application` specific `scope` to which the configuration of the entry belongs to - + slug (string, required) - The identifier of the entry that is unique within the namespace created by `organization`, `application` and `scope` + + organization: `apache` (string, required) - The `organization` who built the `application` for which the configuration of the entry is meant + + application: `tomcat` (string, required) - The `application` to which the configuration of the entry belongs to + + scope: `server.xml` (string, required) - The `application` specific `scope` to which the configuration of the entry belongs to + + slug: `tomcat9-serverxml-example` (string, required) - The identifier of the entry that is unique within the namespace created by `organization`, `application` and `scope` + Request + Headers @@ -711,8 +715,8 @@ Offers to convert a supplied configuration snippet from one format into another - `CONVERT_SUCCESSFUL` if the conversion ran without errors + output (object) - + format (string) - The requested output format. - + snippet (string) - The supplied snippet converted into the output format. + + format: `json` (string) - The requested output format. + + snippet: `{"some-variable": "some special value"}` (string) - The supplied snippet converted into the output format. + Response 400 (application/json) + Attributes (Error Response) @@ -759,39 +763,44 @@ Returns a list of supported configuration formats. In general this is a list of ## User List (object) -+ elements (number) - How many users the response list contains ++ elements: `1` (number) - How many users the response list contains + users (array[User Preview]) - A list of previews for users -+ offset (number) - How many entries have been skipped for the output; this information can be used for pagination -+ remaining (number) - How many entries have not been displayed yet; when adding this value to the offset (and not exceeding the row limit), all entries should have been displayed once ++ offset: `0` (number) - How many entries have been skipped for the output; this information can be used for pagination ++ remaining: `0` (number) - How many entries have not been displayed yet; when adding this value to the offset (and not exceeding the row limit), all entries should have been displayed once ## User Preview (object) -+ username (string) - The users name -+ email (string) - The users email -+ rank (enum[number]) - The users rank (higher means more permissions) ++ username: `Namoshek` (string) - The users name ++ email: `mail@example.com` (string) - The users email ++ rank: `10` (enum[number]) - The users rank (higher means more permissions) + Members + `10` - Normal user + `50` - Moderator + `100` - Admin -+ created_at (number) - A timestamp of the moment when the user has been created ++ created_at: `1475477453` (number) - A timestamp of the moment when the user has been created ## Entry List (object) -+ elements (number) - How many entries the response list contains ++ elements: `1` (number) - How many entries the response list contains + entries (array[Entry Preview]) - A list of previews for entries -+ offset (number) - How many entries have been skipped for the output; this information can be used for pagination -+ remaining (number) - How many entries have not been displayed yet; when adding this value to the offset (and not exceeding the row limit), all entries should have been displayed once -+ formats (array[string]) - A list of available (enabled) configuration formats; formats in this list can be selected for export ++ offset: `0` (number) - How many entries have been skipped for the output; this information can be used for pagination ++ remaining: `0` (number) - How many entries have not been displayed yet; when adding this value to the offset (and not exceeding the row limit), all entries should have been displayed once ## Entry Preview (object) -+ key (string) - Storage path of the entry and also the unique identifier -+ title (string) - How the entry/snippet has been named by the creator -+ description (string) - A description of the entry -+ author (string) - The username of the creator of the entry -+ created_at (number) - A timestamp of the moment when the entry has been created ++ key: `apache/tomcat/server.xml/tomcat9-serverxml-example` (string) - Storage path of the entry and also the unique identifier ++ title: `Tomcat 9 configuration for server.xml` (string) - How the entry/snippet has been named by the creator ++ description: `The server.xml is Tomcats main configuration file and therefore very important. ...` (string) - A description of the entry ++ author: `Namoshek` (string) - The username of the creator of the entry ++ created_at: `1475478234` (number) - A timestamp of the moment when the entry has been created + +## Converted Snippet (object) + ++ format: `xml` (string) - A configuration format ++ plugin: `xmltool` (string) - The name of the plugin used for the conversion ++ value: `...` (string) - The configuration snippet in above mentioned format ## Conversion Format (object) -+ format (string) - The configuration format/language (e.g. ini, xml, csv, ...) -+ plugin (string) - The name of the plugin that offers the format (e.g. simpleini, xmltool, csvstorage, ...) ++ format: `ini` (string) - The configuration format/language (e.g. ini, xml, csv, ...) ++ plugin: `simpleini` (string) - The name of the plugin that offers the format (e.g. simpleini, xmltool, csvstorage, ...) From 06d61aeff14f41a2e0d31f6248f96be1b91f40dd Mon Sep 17 00:00:00 2001 From: Namoshek Date: Mon, 3 Oct 2016 10:02:42 +0200 Subject: [PATCH 41/54] rest-backend: api-description updated (additional error for raw format export) --- doc/api_blueprints/snippet-sharing.apib | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/api_blueprints/snippet-sharing.apib b/doc/api_blueprints/snippet-sharing.apib index aacd227af7d..f5f4c1d8b65 100644 --- a/doc/api_blueprints/snippet-sharing.apib +++ b/doc/api_blueprints/snippet-sharing.apib @@ -422,6 +422,7 @@ Returns detailed information about the entry with the specified key (path). If t A comprehensive list of possible errors: - `ENTRY_UNSUPPORTED_FORMAT` if an unsupported `raw` format has been supplied + - `ENTRY_UNABLE_TO_EXPORT_SNIPPET` if the snippet can not be represented using the submitted `raw` format + Response 404 (application/json) + Attributes (Error Response) From b2f3aacb2e3281cecf772863a0d00644c972a252 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Mon, 3 Oct 2016 17:32:07 +0200 Subject: [PATCH 42/54] rest-backend: api-description updated (formats resource fixed) --- doc/api_blueprints/snippet-sharing.apib | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api_blueprints/snippet-sharing.apib b/doc/api_blueprints/snippet-sharing.apib index f5f4c1d8b65..eee3353ce70 100644 --- a/doc/api_blueprints/snippet-sharing.apib +++ b/doc/api_blueprints/snippet-sharing.apib @@ -746,7 +746,7 @@ Offers to convert a supplied configuration snippet from one format into another - `CONVERT_UNABLE_TO_PARSE_SNIPPET` if the submitted `input.snippet` could not be parsed properly - `CONVERT_UNABLE_TO_CONVERT_SNIPPET` if the submitted `input.snippet` can not be represented using the submitted `output.format` -## Supported conversion formats [GET /formats] +## Supported conversion formats [GET /conversion/formats] Returns a list of supported configuration formats. In general this is a list of formats for which plugins are available and installed. From 00824b2d9c65ada05f3f22800cace14a4a758faf Mon Sep 17 00:00:00 2001 From: Namoshek Date: Thu, 6 Oct 2016 13:56:52 +0200 Subject: [PATCH 43/54] rest-backend: api-description updated (fixed error code to match schema) --- doc/api_blueprints/snippet-sharing.apib | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api_blueprints/snippet-sharing.apib b/doc/api_blueprints/snippet-sharing.apib index eee3353ce70..5657090131b 100644 --- a/doc/api_blueprints/snippet-sharing.apib +++ b/doc/api_blueprints/snippet-sharing.apib @@ -221,7 +221,7 @@ This method can be used to register for the service by creating a new user accou + i18n (string) - A unique token representing above error description message; can be used for internationalization in frontends A comprehensive list of possible errors: - - `USER_CREATE_USERNAME_DOES_ALREADY_EXIST` if the supplied `username` is already taken + - `USER_CREATE_USER_DOES_ALREADY_EXIST` if the supplied `username` is already taken ## Update user [PUT /{name}] From 4d033c2015d9923b3c2ee87c73273e309d3ab20f Mon Sep 17 00:00:00 2001 From: Namoshek Date: Fri, 7 Oct 2016 10:35:43 +0200 Subject: [PATCH 44/54] rest-backend: api-description updated (removed not necessary 'data' layer in snippet details response) --- doc/api_blueprints/snippet-sharing.apib | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/doc/api_blueprints/snippet-sharing.apib b/doc/api_blueprints/snippet-sharing.apib index 5657090131b..0dcdeab7161 100644 --- a/doc/api_blueprints/snippet-sharing.apib +++ b/doc/api_blueprints/snippet-sharing.apib @@ -394,19 +394,18 @@ Returns detailed information about the entry with the specified key (path). If t + Response 200 (application/json) + Attributes (object) - + data (object) - The actual details about the entry - + key (object) - The key and its separate parts - + full: `apache/tomcat/server.xml/tomcat9-serverxml-example` (string) - The full key (path) of the entry - + organization: `apache` (string) - The organization of the application to which the snippet belongs to - + application: `tomcat` (string) - The application to which the snippet belongs to - + scope (string): `server.xml` - The application internal scope for the configuration snippet - + slug (string): `tomcat9-serverxml-example` - The identifying slug of the entry that is unique within the namespace created by `organization`, `application` and `scope` - + meta (object) - Additional information about the entry - + title: `Tomcat 9 configuration for server.xml` (string) - The descriptive title of the entry - + description: `The server.xml is Tomcats main configuration file and therefore very important. ...` (string) - The extended description of the entry - + author: `Namoshek` (string) - The name of the creator of the entry - + created_at: `1475478234` (number) - A timestamp of the creation date of the entry - + value (array[Converted Snippet]) + + key (object) - The key and its separate parts + + full: `apache/tomcat/server.xml/tomcat9-serverxml-example` (string) - The full key (path) of the entry + + organization: `apache` (string) - The organization of the application to which the snippet belongs to + + application: `tomcat` (string) - The application to which the snippet belongs to + + scope (string): `server.xml` - The application internal scope for the configuration snippet + + slug (string): `tomcat9-serverxml-example` - The identifying slug of the entry that is unique within the namespace created by `organization`, `application` and `scope` + + meta (object) - Additional information about the entry + + title: `Tomcat 9 configuration for server.xml` (string) - The descriptive title of the entry + + description: `The server.xml is Tomcats main configuration file and therefore very important. ...` (string) - The extended description of the entry + + author: `Namoshek` (string) - The name of the creator of the entry + + created_at: `1475478234` (number) - A timestamp of the creation date of the entry + + value (array[Converted Snippet]) + Response 200 (text/plain) From 072cc16ba82518079848a9dbc18f1e6e399d8c3e Mon Sep 17 00:00:00 2001 From: Namoshek Date: Fri, 7 Oct 2016 10:41:08 +0200 Subject: [PATCH 45/54] rest-backend: api-description updated (added more key-information to the entry list + removed description, which is a detail) --- doc/api_blueprints/snippet-sharing.apib | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/doc/api_blueprints/snippet-sharing.apib b/doc/api_blueprints/snippet-sharing.apib index 0dcdeab7161..238510dda4c 100644 --- a/doc/api_blueprints/snippet-sharing.apib +++ b/doc/api_blueprints/snippet-sharing.apib @@ -788,9 +788,13 @@ Returns a list of supported configuration formats. In general this is a list of ## Entry Preview (object) -+ key: `apache/tomcat/server.xml/tomcat9-serverxml-example` (string) - Storage path of the entry and also the unique identifier ++ key (object) - Detailed information to the key of the entry + + full: `apache/tomcat/server.xml/tomcat9-serverxml-example` (string) - Storage path of the entry and also the unique identifier + + organization: `apache` (string) - The name of the organization which created the application of the snippet + + application: `tomcat` (string) - The name of the application for which the snippet is meant + + scope: `server.xml` (string) - The application scope of the configuration snippet + + slug: `tomcat9-serverxml-example` (string) - The slug of the configuration snippet + title: `Tomcat 9 configuration for server.xml` (string) - How the entry/snippet has been named by the creator -+ description: `The server.xml is Tomcats main configuration file and therefore very important. ...` (string) - A description of the entry + author: `Namoshek` (string) - The username of the creator of the entry + created_at: `1475478234` (number) - A timestamp of the moment when the entry has been created From 1a32ff89b7f7764a238f998b343f74b4a735f357 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Fri, 7 Oct 2016 14:21:18 +0200 Subject: [PATCH 46/54] rest-backend: api-description updated (added validated flag to exports) --- doc/api_blueprints/snippet-sharing.apib | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/api_blueprints/snippet-sharing.apib b/doc/api_blueprints/snippet-sharing.apib index 238510dda4c..e3d3a99f1d7 100644 --- a/doc/api_blueprints/snippet-sharing.apib +++ b/doc/api_blueprints/snippet-sharing.apib @@ -717,6 +717,7 @@ Offers to convert a supplied configuration snippet from one format into another + output (object) + format: `json` (string) - The requested output format. + snippet: `{"some-variable": "some special value"}` (string) - The supplied snippet converted into the output format. + + validated: `true` - Whether the `snippet` passed the round-trip validation or not (no loss of information during export) + Response 400 (application/json) + Attributes (Error Response) @@ -803,6 +804,7 @@ Returns a list of supported configuration formats. In general this is a list of + format: `xml` (string) - A configuration format + plugin: `xmltool` (string) - The name of the plugin used for the conversion + value: `...` (string) - The configuration snippet in above mentioned format ++ validated: `true` - Whether the `value` passed the round-trip validation or not (no loss of information during export) ## Conversion Format (object) From 35048fc46ab35ad6fa017d7a62b412379cb5aa67 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Tue, 11 Oct 2016 15:56:06 +0200 Subject: [PATCH 47/54] rest-backend: api-description updated (users sortable by rank) --- doc/api_blueprints/snippet-sharing.apib | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/api_blueprints/snippet-sharing.apib b/doc/api_blueprints/snippet-sharing.apib index e3d3a99f1d7..f987b14bbcd 100644 --- a/doc/api_blueprints/snippet-sharing.apib +++ b/doc/api_blueprints/snippet-sharing.apib @@ -98,8 +98,9 @@ Retrieves a list of users. The result can be adjusted by additional, but optiona + Default: `username` + Members + `username` - The users name - + `email` - email + + `email` - The users email address + `created_at` - Creation date + + `rank` - The users rank + filter (string, optional) - Only users containing the search string in either their name or their email will be added to the output. + filterby (enum[string], optional) - On what fields the filter should be applied to (i.e. what fields to involve in search) + Default: `all` From ad2eccbc5a0de1d3be018eacb04d3285e127b824 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Tue, 11 Oct 2016 15:58:41 +0200 Subject: [PATCH 48/54] rest-backend: api-description updated (user permission check for create entry function) --- doc/api_blueprints/snippet-sharing.apib | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/api_blueprints/snippet-sharing.apib b/doc/api_blueprints/snippet-sharing.apib index f987b14bbcd..f5f7c6b8f55 100644 --- a/doc/api_blueprints/snippet-sharing.apib +++ b/doc/api_blueprints/snippet-sharing.apib @@ -436,6 +436,8 @@ Returns detailed information about the entry with the specified key (path). If t Can be used to create a new entry in the database. An entry consists of a unique key (path) that is built from several individual inputs, a title, description and a configuration snippet in any supported format. +This operation requires a user account with normal permissions (rank 10) or higher. + + Request (application/json) + Headers @@ -531,6 +533,7 @@ Can be used to create a new entry in the database. An entry consists of a unique A comprehensive list of possible errors: - `NEED_AUTHENTICATION` if no valid session token has been supplied or the user for whom the token has been created does not exist (anymore) + - `USER_INSUFFICIENT_PERMISSIONS` if the currently authenticated user has insufficient rights to create an entry (i.e. user with reduced rights) + Response 406 (application/json) + Attributes (Error Response) From e79d841188094219fc62d0e57f5f4cb101ec61a5 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Sun, 16 Oct 2016 11:15:47 +0200 Subject: [PATCH 49/54] rest-backend: api-description updated (added plugin statuses to formats list + small structure change) --- doc/api_blueprints/snippet-sharing.apib | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/api_blueprints/snippet-sharing.apib b/doc/api_blueprints/snippet-sharing.apib index f5f7c6b8f55..5576208d53f 100644 --- a/doc/api_blueprints/snippet-sharing.apib +++ b/doc/api_blueprints/snippet-sharing.apib @@ -813,4 +813,6 @@ Returns a list of supported configuration formats. In general this is a list of ## Conversion Format (object) + format: `ini` (string) - The configuration format/language (e.g. ini, xml, csv, ...) -+ plugin: `simpleini` (string) - The name of the plugin that offers the format (e.g. simpleini, xmltool, csvstorage, ...) ++ plugin (object) - Informations about the plugin that this format represents + + name: `simpleini` (string) - The name of the plugin that offers the format (e.g. simpleini, xmltool, csvstorage, ...) + + statuses (array[string]) - A list of statuses that this plugin has From d9b5a02d29de76f235dfd4dd5a9739c7426af755 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Tue, 25 Oct 2016 14:46:46 +0200 Subject: [PATCH 50/54] rest-backend: api-description updated (added tags to entry output) --- doc/api_blueprints/snippet-sharing.apib | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/api_blueprints/snippet-sharing.apib b/doc/api_blueprints/snippet-sharing.apib index 5576208d53f..072fa655e83 100644 --- a/doc/api_blueprints/snippet-sharing.apib +++ b/doc/api_blueprints/snippet-sharing.apib @@ -405,6 +405,7 @@ Returns detailed information about the entry with the specified key (path). If t + title: `Tomcat 9 configuration for server.xml` (string) - The descriptive title of the entry + description: `The server.xml is Tomcats main configuration file and therefore very important. ...` (string) - The extended description of the entry + author: `Namoshek` (string) - The name of the creator of the entry + + tags: `tomcat9`, `webserver` (array[string]) - A list of tags assigned to the entry + created_at: `1475478234` (number) - A timestamp of the creation date of the entry + value (array[Converted Snippet]) @@ -801,6 +802,7 @@ Returns a list of supported configuration formats. In general this is a list of + slug: `tomcat9-serverxml-example` (string) - The slug of the configuration snippet + title: `Tomcat 9 configuration for server.xml` (string) - How the entry/snippet has been named by the creator + author: `Namoshek` (string) - The username of the creator of the entry ++ tags: `tomcat9`, `webserver` (array[string]) - A list of tags assigned to the entry + created_at: `1475478234` (number) - A timestamp of the moment when the entry has been created ## Converted Snippet (object) From 0e1e28cb7c9813cbf3db5730ecc65fff07a8bc58 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Tue, 25 Oct 2016 14:52:49 +0200 Subject: [PATCH 51/54] rest-backend: api-description updated --- doc/api_blueprints/snippet-sharing.apib | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/doc/api_blueprints/snippet-sharing.apib b/doc/api_blueprints/snippet-sharing.apib index 072fa655e83..0a38a98c154 100644 --- a/doc/api_blueprints/snippet-sharing.apib +++ b/doc/api_blueprints/snippet-sharing.apib @@ -6,11 +6,17 @@ HOST: api.libelektra.org This is a description of the API provided by the REST service that can be used to share, search and download configuration snippets. -# API Description [/] +# API Description [/{?raw}] ## List API methods [GET] -Returns an overview of available API methods with required parameters and a description. +Returns an overview of available API methods with required parameters and a description. By default a nicely formatted HTML version of the API specification will be returned. + ++ Parameters + + raw (boolean, optional) - Whether a plain-text, machine-readable blueprint should be returned. + + Default: `false` + ++ Response 200 (text/plain; charset=utf-8) + Response 200 (text/html; charset=utf-8) From 586abb1965c2eba03f9384f68cae38aa95c0f37f Mon Sep 17 00:00:00 2001 From: Namoshek Date: Tue, 25 Oct 2016 14:57:02 +0200 Subject: [PATCH 52/54] rest-backend: api-description updated (changed row limit from 200 to 1000000) --- doc/api_blueprints/snippet-sharing.apib | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/api_blueprints/snippet-sharing.apib b/doc/api_blueprints/snippet-sharing.apib index 0a38a98c154..d6d5dab4b89 100644 --- a/doc/api_blueprints/snippet-sharing.apib +++ b/doc/api_blueprints/snippet-sharing.apib @@ -94,7 +94,7 @@ Retrieves a list of users. The result can be adjusted by additional, but optiona + offset (number, optional) - How many entries to skip for the output, can be used for pagination. + Default: `0` + rows (number, optional) - How many entries will be added to the output at max. - + Default: `200` + + Default: `1000000` + sort (enum[string], optional) - How to sort the entries for the output. + Default: `asc` + Members @@ -356,7 +356,7 @@ Returns a list of database entries. The result can be adjusted by additional, bu + offset: `0` (number, optional) - How many entries to skip for the output, can be used for pagination. + Default: `0` + rows: `1` (number, optional) - How many entries will be added to the output at max. - + Default: `200` + + Default: `1000000` + sort (enum[string], optional) - How to sort the entries for the output. + Default: `asc` + Members From 0d1396ed3a128a646d09f1b62218d50debcedc29 Mon Sep 17 00:00:00 2001 From: Namoshek Date: Wed, 16 Nov 2016 14:48:28 +0100 Subject: [PATCH 53/54] rest-backend: api-description updated (status code & header fixed for root of api) --- doc/api_blueprints/snippet-sharing.apib | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/api_blueprints/snippet-sharing.apib b/doc/api_blueprints/snippet-sharing.apib index d6d5dab4b89..682d8639ef3 100644 --- a/doc/api_blueprints/snippet-sharing.apib +++ b/doc/api_blueprints/snippet-sharing.apib @@ -16,9 +16,10 @@ Returns an overview of available API methods with required parameters and a desc + raw (boolean, optional) - Whether a plain-text, machine-readable blueprint should be returned. + Default: `false` -+ Response 200 (text/plain; charset=utf-8) ++ Response 303 + + Headers -+ Response 200 (text/html; charset=utf-8) + Location: * ## API Version [GET /version] From 8bb42ccdaab94de621e9092f458148e0cd978d1a Mon Sep 17 00:00:00 2001 From: Namoshek Date: Wed, 23 Nov 2016 19:37:19 +0100 Subject: [PATCH 54/54] rest-backend: api-description updated (changed host) --- doc/api_blueprints/snippet-sharing.apib | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api_blueprints/snippet-sharing.apib b/doc/api_blueprints/snippet-sharing.apib index 682d8639ef3..f4f5ea76369 100644 --- a/doc/api_blueprints/snippet-sharing.apib +++ b/doc/api_blueprints/snippet-sharing.apib @@ -1,5 +1,5 @@ FORMAT: 1A -HOST: api.libelektra.org +HOST: restapi.libelektra.org # REST service API for sharing configuration snippets