From 8a0ce7cac4682fb49205da661ce4b2fd93bd3f2c Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Wed, 6 Nov 2024 18:29:30 +0100 Subject: [PATCH 1/2] Api name (#12) * Update API-design-guidelines.md * Update API-design-guidelines.md * Clarifications on api-name, filenames and servers object * Revert "Update API-design-guidelines.md" This reverts commit 1353c82833446ead390b12cb13edec135ee30a96. --------- Co-authored-by: rartych --- documentation/API-design-guidelines.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index cac51128..4b78e64c 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -89,7 +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. | -| **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. | @@ -1221,7 +1222,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)) @@ -1298,6 +1299,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 a59b7aac8241dbcad6ee180eb7467ebc8d6a4527 Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Mon, 18 Nov 2024 13:50:18 +0100 Subject: [PATCH 2/2] Corrected the guideline for multiple servers instances --- documentation/API-design-guidelines.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 4b78e64c..7165bdcc 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -928,7 +928,7 @@ And according to the filtering based on string and enums data, being searched fo **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. +- 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” ly. 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": @@ -1299,7 +1299,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. +If more than one server object instance is listed, the `servers[*].url` property of each instance must have the same string for the `api-name` and `api-version`'. ### 11.2 Published Routes