From 1353c82833446ead390b12cb13edec135ee30a96 Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Wed, 6 Nov 2024 15:03:53 +0100 Subject: [PATCH 1/4] Update API-design-guidelines.md --- documentation/API-design-guidelines.md | 31 ++++++++++++++++---------- 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index cac51128..0bfa3d1b 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -905,6 +905,12 @@ Filtering consists of restricting the number of resources queried by specifying Next, it is specified how it should be used according to the filtering based on the type of data being searched for: a number or a date and the type of operation. Note: Services may not support all attributes for filtering. In case a query includes an attribute for which filtering is not supported, it may be ignored by the service. + +#### Security Considerations +As filtering may reveal sensitive information, privacy and security constraints have to be considered when defining query parameters, e.g. it should not be possible to filter using personal information (such as name, phone number or IP address). + + +#### Filtering operations | **Operation** | Numbers | Dates | |-------------------|------------------------------|-----------------------------------------------| @@ -917,28 +923,29 @@ Note: Services may not support all attributes for filtering. In case a query in And according to the filtering based on string and enums data, being searched for: -| **Operation** | **Strings/enums** | -|---------------|-----------------------| -| equal | `GET .../?name=Juan` | -| non equal | `GET .../?name!=Jonh` | -| Contains | `GET .../?name=~Rafa` | +| **Operation** | **Strings/enums** | +| ----- | ----- | +| equal | `GET .../?type=mobile` | +| non equal | `GET .../?type!=mobile` | +| Contains | `GET .../?type=~str` | **Additional rules**: - The operator "`&`" is evaluated as an AND between different attributes. - A Query Param (attribute) can contain one or n values separated by "`,`". - For operations on numeric, date or enumerated fields, the parameters with the suffixes `.(gte|gt|lte|lt)$` need to be defined, which should be used as comparators for “greater—equal to, greater than, smaller—equal to, smaller than” respectively. Only the parameters needed for given field should be defined e.g., with `.gte` and `.lte` suffixes only. + **Examples**: -- Equals: to search users with the first name "david" and last name "munoz": - - `GET /users?name=david&surname=munoz` - - `GET /users?name=David,Noelia` +- Equals: to search devices with a particular operating system and version or type: + - `GET /device?os=ios&version=17.0.1` + - `GET /device?type=apple,android` - Search for several values separating them by "`,`". - Inclusion: if we already have a filter that searches for "equal" and we want to provide it with the possibility of searching for "inclusion", we must include the character "~" - - `GET /users?name=dav` - - Search for the exact name "dav" - - `GET /users?name=~dav` - - Look for names that include "dav" + - `GET /device?version=17.0.1` + - Search for the exact version "17.0.1" + - `GET /device?version=~17.0` + - Look for version strings that include "17.0" - Greater than / less than: new attributes need to be created with the suffixes `.(gte|gt|lte|lt)$` and included in `get` operation : ```yaml paths: From 14df7190fe0009c5c72ab5c1a68f1e3865be84c0 Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Wed, 6 Nov 2024 16:25:35 +0100 Subject: [PATCH 2/4] Update API-design-guidelines.md --- documentation/API-design-guidelines.md | 1 + 1 file changed, 1 insertion(+) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 0bfa3d1b..33962045 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -89,6 +89,7 @@ This document captures guidelines for the API design in CAMARA project. These gu | **Term** | Description | |----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **API** | Application Programming Interface. It is a rule & specification group (code) that applications follow to communicate between them, used as interface among programs developed with different technologies. | +|**api-name** | `api-name` is a kebab-case string used to create unique names or values of objects and parameters related to given API. For example, for Device Location Verification API, api-name is `location-verification`. | **Body** | HTTP Message body (If exists) is used to carry the entity data associated with the request or response. | | **Camel Case** | It is a kind of define the fields’ compound name or phrases without whitespaces among words. It uses a capital letter at the beginning of each word. There are two different uses:
  • Upper Camel Case: When the first letter of each word is capital.
  • Lower Camel Case: Same to that Upper one, but with the first word in lowercase.
    • | | **Header** | HTTP Headers allow client and server send additional information joined to the request or response. A request header is divided by name (No case sensitive) followed by a colon and the header value (without line breaks). White spaces on the left hand from the value are ignored. | From 2ea01c06b1d7cf1feae4318b73ef3cefd52c6f80 Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Wed, 6 Nov 2024 17:31:04 +0100 Subject: [PATCH 3/4] Clarifications on api-name, filenames and servers object --- documentation/API-design-guidelines.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 33962045..b8418ab5 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -89,8 +89,8 @@ This document captures guidelines for the API design in CAMARA project. These gu | **Term** | Description | |----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **API** | Application Programming Interface. It is a rule & specification group (code) that applications follow to communicate between them, used as interface among programs developed with different technologies. | -|**api-name** | `api-name` is a kebab-case string used to create unique names or values of objects and parameters related to given API. For example, for Device Location Verification API, api-name is `location-verification`. -| **Body** | HTTP Message body (If exists) is used to carry the entity data associated with the request or response. | +|**api-name** | `api-name` is a kebab-case string used to create unique names or values of objects and parameters related to given API. For example, for Device Location Verification API, api-name is `location-verification`.| +| **Body** | HTTP Message body (If exists) is used to carry the entity data associated with the request or response. | | **Camel Case** | It is a kind of define the fields’ compound name or phrases without whitespaces among words. It uses a capital letter at the beginning of each word. There are two different uses:
  • Upper Camel Case: When the first letter of each word is capital.
  • Lower Camel Case: Same to that Upper one, but with the first word in lowercase.
    • | | **Header** | HTTP Headers allow client and server send additional information joined to the request or response. A request header is divided by name (No case sensitive) followed by a colon and the header value (without line breaks). White spaces on the left hand from the value are ignored. | | **HTTP** | Hypertext Transfer Protocol (HTTP) is a communication protocol that allows the information transfer using files (XHTML, HTML…) in World Wide Web. | @@ -1229,7 +1229,7 @@ API documentation usually consists of: - Reference information to inform customers of every detail of your API. Below considerations should be checked when an API is documented: -- The API functionalities must be implemented following the specifications of the [Open API version 3.0.3](https://spec.openapis.org/oas/v3.0.3) using the .yaml or .json file extension. +- The API functionalities must be implemented following the specifications of the [Open API version 3.0.3](https://spec.openapis.org/oas/v3.0.3) using `api-name` as the filename and the `.yaml` or `.json` file extension. - The API specification structure should have the following parts: - General information ([Section 11.1](#111-general-information)) - Published Routes ([Section 11.2](#112-published-routes)) @@ -1306,6 +1306,7 @@ servers: default: http://localhost:9091 description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath` ``` +If more than one server object instances are listed, each `servers[*].url` property must have the same string for the `api-name` and `api-version` in respective instance. ### 11.2 Published Routes From f09db45427273ffe5f7fff6f455f76dc02c5f3c8 Mon Sep 17 00:00:00 2001 From: rartych Date: Wed, 6 Nov 2024 18:06:21 +0100 Subject: [PATCH 4/4] Revert "Update API-design-guidelines.md" This reverts commit 1353c82833446ead390b12cb13edec135ee30a96. --- documentation/API-design-guidelines.md | 31 ++++++++++---------------- 1 file changed, 12 insertions(+), 19 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index b8418ab5..4b78e64c 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -906,12 +906,6 @@ Filtering consists of restricting the number of resources queried by specifying Next, it is specified how it should be used according to the filtering based on the type of data being searched for: a number or a date and the type of operation. Note: Services may not support all attributes for filtering. In case a query includes an attribute for which filtering is not supported, it may be ignored by the service. - -#### Security Considerations -As filtering may reveal sensitive information, privacy and security constraints have to be considered when defining query parameters, e.g. it should not be possible to filter using personal information (such as name, phone number or IP address). - - -#### Filtering operations | **Operation** | Numbers | Dates | |-------------------|------------------------------|-----------------------------------------------| @@ -924,29 +918,28 @@ As filtering may reveal sensitive information, privacy and security constraints And according to the filtering based on string and enums data, being searched for: +| **Operation** | **Strings/enums** | +|---------------|-----------------------| +| equal | `GET .../?name=Juan` | +| non equal | `GET .../?name!=Jonh` | +| Contains | `GET .../?name=~Rafa` | -| **Operation** | **Strings/enums** | -| ----- | ----- | -| equal | `GET .../?type=mobile` | -| non equal | `GET .../?type!=mobile` | -| Contains | `GET .../?type=~str` | **Additional rules**: - The operator "`&`" is evaluated as an AND between different attributes. - A Query Param (attribute) can contain one or n values separated by "`,`". - For operations on numeric, date or enumerated fields, the parameters with the suffixes `.(gte|gt|lte|lt)$` need to be defined, which should be used as comparators for “greater—equal to, greater than, smaller—equal to, smaller than” respectively. Only the parameters needed for given field should be defined e.g., with `.gte` and `.lte` suffixes only. - **Examples**: -- Equals: to search devices with a particular operating system and version or type: - - `GET /device?os=ios&version=17.0.1` - - `GET /device?type=apple,android` +- Equals: to search users with the first name "david" and last name "munoz": + - `GET /users?name=david&surname=munoz` + - `GET /users?name=David,Noelia` - Search for several values separating them by "`,`". - Inclusion: if we already have a filter that searches for "equal" and we want to provide it with the possibility of searching for "inclusion", we must include the character "~" - - `GET /device?version=17.0.1` - - Search for the exact version "17.0.1" - - `GET /device?version=~17.0` - - Look for version strings that include "17.0" + - `GET /users?name=dav` + - Search for the exact name "dav" + - `GET /users?name=~dav` + - Look for names that include "dav" - Greater than / less than: new attributes need to be created with the suffixes `.(gte|gt|lte|lt)$` and included in `get` operation : ```yaml paths: