Merge branch 'camaraproject:main' into main

camaraproject · Aug 29, 2023 · 3022426 · 3022426
2 parents e87815e + 6684b6c
commit 3022426
Show file tree

Hide file tree

Showing 3 changed files with 78 additions and 9 deletions.
diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md
@@ -258,7 +258,6 @@ PUT |  Update | Replaces a specific resource. Returns the resource URL when the
 DELETE | Delete | Delete a specific resource.  |
 PATCH |  Update | Updates a specific resource, applying all changes at the same time. If resource does not exist, it will be created. Returns the resource URL when the update ends. If any error occurs during the update, all of them will be cancelled.   |
 OPTIONS | Read | Returns a 200 OK with an allowed methods list in the specific resource destined to the header allowed joined to an HTML document about the resource + an API Doc link.  |
-HEAD | Read | Returns the resource actual status without message body. |
 
 In this document will be defined the principal verbs to use in the API definition.
 
@@ -765,7 +764,7 @@ With the aim of standardizing the request observability and traceability process
 
 One of the key points in the API definition process is to specify and validate the security needs that will be maintained to guarantee data integrity and access control. There are multiple ways to secure a RESTful API, e.g. basic authentication, OAuth, etc., but one thing is for sure: RESTful APIs should be stateless, so authentication/authorization requests should not rely on cookies or sessions. Instead, each API request must come with some form of authentication credentials that must be validated on the server for each request.
 
-Basic idea in terms of security is to understand that various types of data will require different levels of security, depending on the confidentiality of the data you are trying to obtain and the level of trust between Telefónica and the consumer.
+Basic idea in terms of security is to understand that various types of data will require different levels of security, depending on the confidentiality of the data you are trying to obtain and the level of trust between the API Provider and the consumer.
 
 
 ### 10.1 API REST Security
@@ -953,6 +952,20 @@ Below considerations should be checked when an API is documented:
    -  Response Structure ([Section 11.4](#114-response-structure))
    -  Data Definitions ([Section 11.5](#115-data-definitions))
    -  OAuth Definition ([Section 11.6](#116-oauth-definition))
+- To avoid issues with implementation using Open API generators:
+  - Reserved words must not be used in the following parts of an API specification:
+    - Path and operation names
+    - Path or query parameter names
+    - Request and response body property names
+    - Security schemes
+    - Component names
+    - OperationIds
+  - A reserved word is one whose usage is reserved by any of the following Open API generators:
+    - [Python Flask](https://openapi-generator.tech/docs/generators/python-flask/#reserved-words)
+    - [OpenAPI Generator (Java)](https://openapi-generator.tech/docs/generators/java/#reserved-words)
+    - [OpenAPI Generator (Go)](https://openapi-generator.tech/docs/generators/go/#reserved-words)
+    - [OpenAPI Generator (Kotlin)](https://openapi-generator.tech/docs/generators/kotlin/#reserved-words)
+    - [OpenAPI Generator (Swift5)](https://openapi-generator.tech/docs/generators/swift5#reserved-words)
 
 ### 11.1 General Information
 

diff --git a/documentation/Glossary.md b/documentation/Glossary.md
@@ -3,29 +3,29 @@
 
 | Term      | Description | Usage in API (Parameter/Field) | Alternative developer-friendly terms |
 | ------------ | ----------- | ----------- |  ----------- |
-| **Device** | End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators.   | device |  |  |
+| **Device** |End-user equipment able to connect to a network. Examples of devices include smartphones, home gateways or IoT sensors/actuators.  | device |  |  |
 | **Application Server** | A server hosting backend applications to deliver some business logic to clients. | applicationServer |  |  |
 | **Phone Number** |A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard.  | phoneNumber |  |  |
-| **Network Access Identifier** |  A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator.| networkAccessIdentifier  |  |  |
+| **Network Access Identifier** |  A public identifier addressing a subscription in a network, defined in [IETF RFC 7542](https://datatracker.ietf.org/doc/rfc7542/). In 3GPP mobile networks one such option is the General Public Subscriber Identifier (GPSI) formatted with the "External Identifier" as ({Local Identifier}@{Domain Identifier}). Unlike the phone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator. | networkAccessIdentifier  |  |  |
 | **IP v4 Address** | Identifier of a node in a network using Internet Protocol version 4 (IPv4). IPv4 uses 32-bit addresses, which are insufficient to allocate unique addresses to all current devices. In order to mitigate this, network operators use Network Address Translation (NAT), mapping a private IP address space to a public one. | ipv4Address |  |  |
 | **IP v6 Address** |  | ipv6Address |  |  |  |  |
-| **Carrier Billing** (a.k.a. Direct Carrier Billing) | An online payment process which allows users to make purchases by charging payments against OB Billing Systems, accordingly to the user's configuration in the OB. In a common usage in the industry, the payment is processed on current account balance or charged on next bill generated for this line | N/A | N/A |
+| **Carrier Billing** (a.k.a. Direct Carrier Billing) | An online payment process which allows users to make purchases by charging payments against Telco Operator Billing Systems, accordingly to the user's configuration in the Telco Operator. In a common usage in the industry, the payment is processed on current account balance or charged on next bill generated for this line | N/A | N/A |
 | **Purchase** | The action of acquiring a (set of) good(s)/service(s). Order fulfilment is not triggered from this request as it relies on merchant's responsibility |purchaseId | purchaseIdentifier |
 | **Payment** | The process of paying for a (set of) good(s)/service(s) | paymentId | paymentIdentifier |
-| **1-STEP Payment** | Payment process performed in one phase (i.e. one action), that involves all the OB Carrier Billing Systems checking and trigger the charging request against Billing Systems | N/A | N/A |
+| **1-STEP Payment** | Payment process performed in one phase (i.e. one action), that involves all the Telco Operator Carrier Billing Systems checking and trigger the charging request against Billing Systems | N/A | N/A |
 | **2-STEP Payment** | Payment process performed in two phases (i.e. two actions). First action deals with payment preparation request to guarantee the reservation of the involved amount. Second action is an explicit confirmation or cancellation of the payment by the user. Any payment not confirmed/cancelled by a given user is discarded after some time in order to avoid inconsistency in the billing systems | N/A | N/A |
 | **IP Address** | An single internet protocol address, specified using either "dotted-decimal" format (for IPv4) or IETF 5952 format (for IPv6). The source ip address is the ip address of the message sender, and the destination ip address is the ip address of the recipient. The description will make it clear which is required. | ip | ipAddress sourceIpAddress destinationIpAddress |
-| **Port** | A 16 bit number (in the range 0 - 65535) used by the TCP (IETF RFC 9293) and UDP (IETF RFC 768) protocols to identify different applications flows and services. The source port is the port alloacted to the message sender, and the destination port is the port allocated to the recipient. The description will make it clear which is required. | TBD | sourcePort destinationPort devicePorts applicationServerPorts  |
+| **Port** | A 16 bit number (in the range 0 - 65535) used by the TCP (IETF RFC 9293) and UDP (IETF RFC 768) protocols to identify different applications flows and services. The source port is the port allocated to the message sender, and the destination port is the port allocated to the recipient. The description will make it clear which is required. | TBD | sourcePort destinationPort devicePorts applicationServerPorts  |
 | **Service Class** | A statement of the required QoS characteristics of a traffic aggregate. Conceptually, a service class refers to applications with similar characteristics and performance requirements. Each service class is mapped to a DSCP value according to RFC4594 guidelines. The DSCP value is used to classify the target home device's traffic so that it can be treated accordingly (i.e. to meet its QoS needs). |serviceClass |  |
 | **Event Type** | Type of event subscribed for notifications. More details and parameter definitions are included in chapter 12 of API Design guidelines.  |  eventType|  |
 | **Latitude** | | latitude |
 | **Longitude** | | longitude |
 | **accuracy** | | accuracy |
-| **Location Verification result** | As value is a boolean, it matches better with an adjective. In future versions we may need to enhance current response model to give mor information about the verification process, for example to deal with partial matches. |locationVerified |
+| **Location Verification result** | As value is a boolean, it matches better with an adjective. In future versions we may need to enhance current response model to give more information about the verification process, for example to deal with partial matches. |locationVerified |
 | **Telco Operator Edge site** | Edge Datacenter where the Application are deployed. Term for the documentation. |N/A|N/A |
 | **API Producer** | Software component, inside the platform, that exposes the CAMARA API. Term for the documentation. |N/A|API Provider |
 | **API Consumer** | Software component in the Application implemented by the Developer, that consumes the CAMARA API produced by the API Producer. Term for the documentation. |N/A|N/A |
-
+| **Suffix: Id vs Identifier** |	Suffix "Id" for unique fields. E.g, ApplicationId (specific code for an Application). Suffix "Identifier" for generic fields, ProductIdentifier (generic variable to identify a family of products)|	e.g. ApplicationId or ProductIdentifier|	N/A|
 
 
 

diff --git a/documentation/MeetingMinutes/MoM-27-07-2023.md b/documentation/MeetingMinutes/MoM-27-07-2023.md
@@ -0,0 +1,56 @@
+*Commonalities Meeting Minutes, 27th July 2023*
+
+## Attendees
+
+| Name | Company |
+| ---- | ------- |
+|Tanja De Groot| Nokia|
+|Toshi Wakayama| KDDI |
+|Randy Levensalor| CableLabs  |
+|Eric Murray |	Vodafone|
+|Kevin Smith |	Vodafone|
+|Patrice Conil |Orange | 
+|Rubén Barrado Gonzalez| Telefonica|
+|Jorge Garcia Hospital| Telefonica|
+|Murat Karabulut |T-Mobile US|
+| Shilpa Padgaonkar | Deutsche Telekom |
+| Rafal Artych | Deutsche Telekom |
+
+## Agenda
+
+* **Preparation for the first subproject release**
+* **Review of issues and PRs**
+* **AOB**
+
+
+| Agenda Item | Description |
+| ----------- | ----------- |
+|Preparation of Commonalities release (Issue [#32](https://github.com/camaraproject/Commonalities/issues/32))|PRs [#23](https://github.com/camaraproject/Commonalities/pull/23) [#39](https://github.com/camaraproject/Commonalities/pull/39) [#40](https://github.com/camaraproject/Commonalities/pull/40) include small changes and corrections in Design Guidelines and Glossary and will be merged, then the first release of Commonalities will be created.  |
+|Issue [#42](https://github.com/camaraproject/WorkingGroups/issues/42) | Usage of ClassName in Mappings section of discriminator - such recommendation should help with some OpenAPI code generators. Please provide feedback.|
+| Issue [#36](https://github.com/camaraproject/Commonalities/issues/36) | Alpha and Beta labels to API versions. Please provide more feedback.|
+| Issue [#31](https://github.com/camaraproject/Commonalities/issues/31) | RFC 7807 error responses to allow API consumers to be reminded of the API definition - the notation defined in RFC 5147, appending  `#line` to the URL is not supported by browsers. Should the link go to the API specs or provider own documentation?|
+| Issue [#29](https://github.com/camaraproject/Commonalities/issues/29) | Lists of code generator reserved words - especially important for Python code generators, can be added to API Design Guidelines - more feedback expected. In the meanwhile, Eric will proceed to create a PR. |
+| Issue [#28](https://github.com/camaraproject/Commonalities/issues/28) | Remove the option of HTTP HEAD requests - not needed in the most of APIs providing short, static responses; possibly useful in Edge Cloud - more feedback expected. In the meanwhile, Eric will proceed to create a PR.|
+| Issue [#25](https://github.com/camaraproject/Commonalities/issues/25) |API Versioning - Aggregation - clarification ongoing in the issue discussion: Awaiting feedback from Chris. |
+| Issue [#8](https://github.com/camaraproject/Commonalities/issues/8) |  OAS for notification event - 2 PRs proposed -[#41](https://github.com/camaraproject/Commonalities/pull/41) - initial proposal and [#43](https://github.com/camaraproject/Commonalities/pull/43) - with Cloudevents format - more discussion in this issue or PRs comments expected.|
+
+
+## Issues that can be closed
+Issue [#5](https://github.com/camaraproject/WorkingGroups/issues/5)
+Issue [#9](https://github.com/camaraproject/WorkingGroups/issues/9)
+Issue [#16](https://github.com/camaraproject/WorkingGroups/issues/16)
+Issue [#27](https://github.com/camaraproject/WorkingGroups/issues/27)
+Issue [#32](https://github.com/camaraproject/WorkingGroups/issues/32)
+
+## PRs that can be merged
+ [#23](https://github.com/camaraproject/Commonalities/pull/23) 
+ [#39](https://github.com/camaraproject/Commonalities/pull/39) 
+ [#40](https://github.com/camaraproject/Commonalities/pull/40)
+
+## AOB
+
+Meeting on 10th Aug is cancelled for summer break.
+
+Next meeting is scheduled on 24th of August.
+
+