diff --git a/documentation/API-DocumentationTemplate.md b/documentation/API-DocumentationTemplate.md index 474569bb..b4147348 100644 --- a/documentation/API-DocumentationTemplate.md +++ b/documentation/API-DocumentationTemplate.md @@ -1,17 +1,17 @@ # API documentation template -| Section | Sub-section | Description | Mandatory | -|----|---|---|-| -| Overview | Introduction | This section gives an overview of the API. It explains the use of the API and gives an insight on its benefits. A few lines on some standard use cases can help better explain the API | Yes | -|| Quick Start|It explains how developers can get started with this API. A good example is the Stripe-API documentation: https://stripe.com/docs/api || -|Authentication and/or Authorization | |It explains how developers/consumers can access the API. Failure to document the authN-authZ schema in a simple and precise way can deter first time API users . |Yes| -|Documentation|Details|This is an optional section/placeholder. It could include some detailed descriptions or diagrams explaining things in further details and the subsection heading could be changed accordingly.| | -| |Endpoint definitions | What does each endpoint do is a critical part of the API documentation. It explains the consumer/developer your internal system. The documentation should explain what an endpoint is for and how it relates to other endpoints. It should also document:
- HTTP verb methods supported.
- Parameters along with description
- HTTP codes expected + HTTP response bodies
- HTTP Request and Response headers
- Pagination details if applicable
If there are any constraints for an endpoint, it should be documented in this section.
It should be made clear if certain endpoints are restricted to only certain roles/users. | Yes | -| |Errors|Error types along with error codes summary table can offer a good reference for the developers working with the API | Yes | -| |Policies|How the developer can discover the usage policy for each endpoint - e.g. limits on requests per second, any regional limitations on what can be returned to the resource representation, etc. These policies will be operator-specific, but the mechanism to discover them should be consistent | No | -| |Code snippets| Copy-paste sample code snippets help developers to get started right away. It helps provide a rich developer experience. This can include sample request examples, and the ability to execute samples directly from the documentation Web page (as per Open API). | No | -| |FAQs| List of frequently asked questions by the early developers/users of the API |No | -| |Terms|Terms of Service |No (N/A for Camara| -| |Release Notes|List of all changes included in the release |Yes| -| |Pricing |Details about pricing |No (N/A for Camara)| -|API Spec || Complete API Spec in YAML format | Yes | +| Section | Sub-section | Description | Mandatory | +|-------------------------------------|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------| +| Overview | Introduction | This section gives an overview of the API. It explains the use of the API and gives an insight on its benefits. A few lines on some standard use cases can help better explain the API | Yes | +| | Quick Start | It explains how developers can get started with this API. A good example is the Stripe-API documentation: https://stripe.com/docs/api | | +| Authentication and/or Authorization | | It explains how developers/consumers can access the API. Failure to document the authN-authZ schema in a simple and precise way can deter first time API users . | Yes | +| Documentation | Details | This is an optional section/placeholder. It could include some detailed descriptions or diagrams explaining things in further details and the subsection heading could be changed accordingly. | | +| | Endpoint definitions | What does each endpoint do is a critical part of the API documentation. It explains the consumer/developer your internal system. The documentation should explain what an endpoint is for and how it relates to other endpoints. It should also document:
- HTTP verb methods supported.
- Parameters along with description
- HTTP codes expected + HTTP response bodies
- HTTP Request and Response headers
- Pagination details if applicable
If there are any constraints for an endpoint, it should be documented in this section.
It should be made clear if certain endpoints are restricted to only certain roles/users.  | Yes | +| | Errors | Error types along with error codes summary table can offer a good reference for the developers working with the API | Yes | +| | Policies | How the developer can discover the usage policy for each endpoint - e.g. limits on requests per second, any regional limitations on what can be returned to the resource representation, etc. These policies will be operator-specific, but the mechanism to discover them should be consistent | No | +| | Code snippets | Copy-paste sample code snippets help developers to get started right away. It helps provide a rich developer experience. This can include sample request examples, and the ability to execute samples directly from the documentation Web page (as per Open API). | No | +| | FAQs | List of frequently asked questions by the early developers/users of the API | No | +| | Terms | Terms of Service | No (N/A for Camara | +| | Release Notes | List of all changes included in the release | Yes | +| | Pricing | Details about pricing | No (N/A for Camara) | +| API Spec | | Complete API Spec in YAML format | Yes | diff --git a/documentation/API-Testing-Guidelines.md b/documentation/API-Testing-Guidelines.md index 6dde1231..82620fc6 100644 --- a/documentation/API-Testing-Guidelines.md +++ b/documentation/API-Testing-Guidelines.md @@ -2,69 +2,69 @@ ## Table of Contents - [Introduction](#introduction) -- [Test plan coverage](#coverage) +- [Test plan coverage](#test-plan-coverage) - [Independent operations](#independent-operations) - [Operations modifying resources](#operations-modifying-resources) - [Notifications](#notifications) - [Error scenarios](#error-scenarios) -- [Test plan design guidelines](#guidelines) - - [Location of feature file](#location) +- [Test plan design guidelines](#test-plan-design-guidelines) + - [Location of feature file](#location-of-feature-files) - [Feature structure](#feature-structure) - [Environment variables](#environment-variables) - - [Background section](#background) + - [Background section](#background-section) - [Scenario structure](#scenario-structure) - [Request setup](#request-setup) - [Request sending](#request-sending) - [Response validation](#response-validation) - [References](#references) -## Introduction +## Introduction This document captures guidelines for the API testing in CAMARA project. These guidelines are applicable to every API to be worked out under the CAMARA initiative. -## Test plan coverage +## Test plan coverage -Based on the decision taken in the [Release Management](https://github.com/camaraproject/ReleaseManagement) and Commonalities working groups, and as documented in [API Release Process](https://wiki.camaraproject.org/display/CAM/API+Release+Process)](https://wiki.camaraproject.org/display/CAM/API+Release+Process#APIReleaseProcess-APIreadinesschecklist), at least one Gherkin feature file per API will be added to the API repo folder for test plans, and this test plan must fulfill the minimum criteria of readiness with respect to API test cases and documentation: +Based on the decision taken in the [Release Management](https://github.com/camaraproject/ReleaseManagement) and Commonalities working groups, and as documented in [API Release Process](https://wiki.camaraproject.org/display/CAM/API+Release+Process)(https://wiki.camaraproject.org/display/CAM/API+Release+Process#APIReleaseProcess-APIreadinesschecklist), at least one Gherkin feature file per API will be added to the API repo folder for test plans, and this test plan must fulfill the minimum criteria of readiness with respect to API test cases and documentation: * Release candidates must have at least a basic API test plan, covering sunny day scenarios. Scenarios are expected to validate that the implemented interface is compliant with the specification, in terms of syntax and support for the mandatory aspects. -* Any public release must include a full test plan, covering both sunny and rainy day scenarios, to be considered stable. This may include unusual or not explicitly specified error scenarios, semantic validations and corner cases. +* Any public release must include a full test plan, covering both sunny and rainy day scenarios, to be considered stable. This may include unusual or not explicitly specified error scenarios, semantic validations, and corner cases. -If subprojects also intend to add test implementations, an aligned single implementation that is agreed among all provider implementors could be added to the main subproject repo. If no alignment is possible, each provider implementer will add the test implementation to their own repos. +If subprojects also intend to add test implementations, an aligned single implementation agreed among all provider implementors could be added to the main subproject repo. If no alignment is possible, each provider implementer will add the test implementation to their own repos. -* Test plans are not expected to certify or measure the quality of the implementation in terms of accuracy or veracity of the response, but to validate that the interface is compliant with the API specification and that the API is fully implemented. +* Test plans are not meant to certify the accuracy or veracity of the implementation's responses but to ensure that the interface complies with the API specification and that the API is fully implemented. * When the API allows options or alternative approaches, the test plan should cover those situations and define the expected behaviour for inputs or options not supported. - - Implementations will need to inform in advance to the API tester about which subset of options are supported. + - Implementations will need to inform in advance to the API tester about which subset of options is supported. -### Independent operations +### Independent operations -Operations that execute an action or retrieve information from the operator, without modifying a resource, will usually be tested in its own dedicated feature file. Splitting a test plan into several features is a test plan design decision, taking into account the complexity of the test plan. +Operations that execute an action or retrieve information from the operator without modifying a resource will usually be tested in its own dedicated feature file. Splitting a test plan into several features is a test plan design decision, taking into account the complexity of the test plan. -Test plan must validate that providing a valid input, a success response is received and that the response body complies with the JSON-schema in the API spec. +Test plan must validate that providing a valid input, a success response is received and that the response body complies with the JSON schema in the API spec. For operations receiving an input request body with optional properties, several scenarios should be included, testing different sets of valid inputs. -### Operations modifying resources +### Operations modifying resources For path resources with CRUD (Create/Read/Update/Delete) operations, some scenario should validate that the new state of the resource is coherent with the result of the operation: * For Create operations: - If operation success returns the created object, validate that the properties of the response object are coherent with the request object - - Validate that the created object can be read by the GET operation for the item id. + - Validate that the GET operation can read the created object for the item id. * For Update operations: - If operation success returns the updated object, validate that the properties of the response object are coherent with the request object - - Validate that the updated object can be read by the GET operation for the item id, with the modified properties. + - Validate that the GET operation can read the updated object for the item id, with the modified properties. * For Delete operations: - Validate that trying to read the successfully deleted object, with the GET operation for the deleted item id, returns the error specified in the API spec, typically 404. -### Notifications +### Notifications For operation with implicit subscriptions: * Check that when a webhook (i.e. callbackURL) is provided, the expected events are received in the `sink`, with the right `sinkCredential`, for those situations specified in the API. -* If the API allows to update a previously provided webhook: +* If the API allows updating a previously provided webhook: - If the `sink` is modified, validate that events are received in the modified value. - If the `sink` can be nullified, validate that events are not longer received. - If the `sinkCredential` is modified, validate that the new token is used for the events. @@ -76,7 +76,7 @@ For the explicit subscriptions model: * For subscriptions that provide `subscriptionMaxEvents`, validate that the subscribed events are not longer received after the maximum events limit is reached. * Validate that after a subscription is deleted, the subscribed events are not longer received. -### Error scenarios +### Error scenarios * All errors explicitly documented in the API spec must be covered by one or more dedicated error scenarios. - In particular operations that expect a `device` object allowing one or more identifiers to be provided, must include scenarios to test the error cases defined, aligned with the device error management section of the API design guidelines. @@ -89,16 +89,16 @@ For operations with a request body, several scenarios are expected to test diffe - Values with invalid format - Mandatory properties are missing -## Test plan design guidelines +## Test plan design guidelines -* Granularity of the feature file must be decided at the project level but it is recommended to: +* Granularity of the feature file must be decided at the project level, but it is recommended to: - group in one file all scenarios testing one closely related API capability (that can cover one or several endpoints). - provide several files when one CAMARA API (yaml) covers several independent functions that can be provided independently -* Third person pronoun usage in feature file is advisable as using the third person, conveys information in a more official manner. +* Third-person pronoun usage in feature file is advisable as using the third person, conveys information in a more official manner. -### Location of feature files +### Location of feature files The feature files will reside under @@ -115,7 +115,7 @@ Filename: - For APIs with several operations that split the test plan in one feature file per operation, recommendation is to add the `operationId` to the api-name as file name: `quality-on-demand-createSession.feature`. - APIs with several feature files, not split by operation, should use the api-name along some other description, e.g.: `quality-on-demand-notifications.feature` -### Feature structure +### Feature structure A feature will typically test an independent API operation or several closely related API operations. It will consist of several scenarios testing the server responses to the API operations under different conditions and input content in the requests, covering both success and error scenarios. Each scenario will validate that the response complies with the expected HTTP status, that the response body syntactically complies with the specified JSON schema, and, when applicable, that some properties have the expected semantic values. @@ -125,27 +125,27 @@ For the Feature description, API name and version must be included. When the fea Feature: CAMARA Device location verification API, v0.2.0 - Operation verifyLocation ``` -### Environment variables +### Environment variables Commonly, some values to fill the request bodies will not be known in advance and cannot be specified as part of the feature file, as they will be specific for the test environment, and they will have to be provided by the implementation to the tester as a separate set of environment or configuration variables. -How those variables are set and feed into the testing execution will depend on the testing tool (Postman environment, context in Behave, etc). +How those variables are set and feed into the testing execution will depend on the testing tool (Postman environment, context in Behave, etc.). A first step is to identify potential environment variables writing the test plan, e.g.: -| variable | description | -| --- | --- | -| apiRoot | API root of the server URL | -| locatedDevice | A device object which location is known by the network when connected. To test all scenarios, at least 2 valid devices are needed | -| knownLatitude | The latitude where locatedDevice is known to be located | -| knownLongitude | The longitude where locatedDevice is known to be located | +| variable | description | +|----------------|-----------------------------------------------------------------------------------------------------------------------------------| +| apiRoot | API root of the server URL | +| locatedDevice | A device object which location is known by the network when connected. To test all scenarios, at least 2 valid devices are needed | +| knownLatitude | The latitude where locatedDevice is known to be located | +| knownLongitude | The longitude where locatedDevice is known to be located | -This list of input data to be requested may kept in a separated file. Structure of this file is yet TBD. +This list of input data to be requested may be kept in a separated file. The Structure of this file is yet TBD. -### Background section +### Background section -At a beginning of the feature file, a `Background` section is expected, including common configuration steps and setting up variables and values which are applicable to every scenario. This way scenarios do not need to to replicate those steps. +At a beginning of the feature file, a `Background` section is expected, including common configuration steps and setting up variables and values which are applicable to every scenario. This way, scenarios do not need to replicate those steps. Background section example: @@ -158,7 +158,7 @@ Background: And the header "x-correlator" is set to a UUID value ``` -### Scenario structure +### Scenario structure * The structure of the steps for API testing will typically be: - A `Given` block setting up the request @@ -177,9 +177,9 @@ E.g.: `@location_verification_10_device_empty` * `Scenario Outline` may be used at convenience with an `Examples` section. -### Request setup +### Request setup -`Given` steps generally put the system in a well-defined state. For API testing, this typically imply setting up the request according to the scenario preconditions, filling the necessary path, query, header and/or body parameters. +`Given` steps generally put the system in a well-defined state. For API testing, this typically implies setting up the request according to the scenario preconditions, filling the necessary path, query, header and/or body parameters. For coherence and to ease reusability of testing implementations, a common syntax should be followed by all testing plans: @@ -221,7 +221,7 @@ Alternatively, instead of specifying exact values for specific parameters or pro Testing plans should identify the list of input values that have to be provided by the implementation, and maintain this list as an asset of the test plan. -### Request sending +### Request sending For scenarios testing individual operations, the request will be sent by means of a single `When` step, indicating the `operationId` specified in the spec, as the `operationId` uniquely identifies the HTTP method and resource path. E.g.: @@ -229,7 +229,7 @@ For scenarios testing individual operations, the request will be sent by means o When the request "{operationId}" is sent ``` -For scenarios involving several requests, subsequent requests may be included as additional `When` steps after the response to the first one is validated. E.g.: +For scenarios involving several requests, further requests may be included as additional `When` steps after the response to the first one is validated. E.g.: ``` Scenario: Delete an item and check that is deleted @@ -240,12 +240,12 @@ Scenario: Delete an item and check that is deleted Then the response status is 404 ``` -But general recommendation is avoid creating complex scenarios and split logic in simpler scenarios as much as possible. +But the general recommendation is to avoid creating complex scenarios and split logic in simpler scenarios as much as possible. -### Response validation +### Response validation -`Then` steps will validate that response is as expected by the scenario. Typically these steps will be written in form of assertions, checking that some condition is complied. +`Then` steps will validate that response is as expected by the scenario. Typically, these steps will be written in the form of assertions, checking that some condition is complied. Typical response validations: @@ -269,7 +269,7 @@ Typical response validations: - the response body complies with the OAS schema at "{oas_schema_json_path}" ``` -- additional constraints for optional or dependant properties in the response body, e.g.: +- additional constraints for optional or dependent properties in the response body, e.g.: ``` - the response property "{json_path}" exists @@ -284,7 +284,7 @@ Typical response validations: - the response property "$.code" is "INVALID_ARGUMENT" ``` -## References +## References * [Feature files]( https://copyprogramming.com/howto/multiple-feature-inside-single-feature-file#multiple-feature-inside-single-feature-file) * [Scenario Identifier](https://support.smartbear.com/cucumberstudio/docs/tests/best-practices.html#scenario-content-set-up-writing-standards) diff --git a/documentation/API-linting-Implementation-Guideline.md b/documentation/API-linting-Implementation-Guideline.md index f26256b0..4b363a27 100644 --- a/documentation/API-linting-Implementation-Guideline.md +++ b/documentation/API-linting-Implementation-Guideline.md @@ -1,8 +1,8 @@ -# CAMARA OpenAPI Linting Rules Implementaion Guideline [ How to integrate the rules into CAMARA repository ] +# CAMARA OpenAPI Linting Rules Implementation Guideline [ How to integrate the rules into CAMARA repository ] ## Introduction -This guide provides instructions how to implement linting rules for the CAMARA APIs using two methods: **[GitHub Actions](API-linting-Implementation-Guideline.md#github-actions-integration)** and **[local deployment](API-linting-Implementation-Guideline.md#github-actions-integration)**, both methods use [Spectral tool](https://docs.stoplight.io/docs/spectral/674b27b261c3c-overview). +This guide provides instructions on how to implement linting rules for the CAMARA APIs using two methods: **[GitHub Actions](API-linting-Implementation-Guideline.md#github-actions-integration)** and **[local deployment](API-linting-Implementation-Guideline.md#github-actions-integration)**, both methods use [Spectral tool](https://docs.stoplight.io/docs/spectral/674b27b261c3c-overview). All needed files are stored in [artifacts subfolder](https://github.com/camaraproject/Commonalities/tree/API-linting-Implementation-Guideline/artifacts/linting_rules). The target method is linting rules integration with CAMARA API subproject repositories using GitHub Actions. @@ -43,12 +43,12 @@ This file consolidates all rules: The rules will be applied to all files with *.yaml extension in '/code/API_definitions/' folder of the repository. Write access to the repository is required to perform these steps. -The output from Spectral can be seen by expanding the step **Run Spectral Linting** of given worflow run Actions section of GitHub repository. +The output from Spectral can be seen by expanding the step **Run Spectral Linting** of the given workflow run Actions section of GitHub repository. ### Megalinter integration -[Megalinter](https://megalinter.io/latest/) is an Open-Source tool for CI/CD workflows that analyzes the consistency of code, configurations and scripts in repository sources. Megalinter supports Spectral linting. +[Megalinter](https://megalinter.io/latest/) is an Open-Source tool for CI/CD workflows that analyzes the consistency of code, configurations, and scripts in repository sources. Megalinter supports Spectral linting. The Megalinter job will be automatically activated once you submit a pull request on the [main/master] branch of the CAMARA repository, as configured in megalinter.yml. The Megalinter configuration consists of the megalinter.yml file containing the necessary settings to run Megalinter and Spectral jobs on GitHub actions. @@ -74,7 +74,7 @@ Additionally, Megalinter also supports linting of YAML files. To enable this, us Save ".spectral.yml" file (contains Linting rules) and lint_function folder (contains JavaScript customized functions) at the root location. -4. Apply spectral rules on API specification loacally: +4. Apply spectral rules on API specification locally: spectral lint openapi.yaml --verbose --ruleset .spectral.yml diff --git a/documentation/Camara_Versioning_Guidelines.md b/documentation/Camara_Versioning_Guidelines.md new file mode 100644 index 00000000..e69de29b diff --git a/documentation/Glossary.md b/documentation/Glossary.md index 9eabab44..911df3fb 100644 --- a/documentation/Glossary.md +++ b/documentation/Glossary.md @@ -1,31 +1,31 @@ # Glossary -| Term | Description | Usage in API (Parameter/Field) | Alternative developer-friendly terms | -| ------------ | ----------- | ----------- | ----------- | -| **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, prefixed with '+'. | phoneNumber | | | -| **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 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 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 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 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| +| Term | Description | Usage in API (Parameter/Field) | Alternative developer-friendly terms | +|-----------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------|---------------------------------------------------------------| +| **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, prefixed with '+'. | phoneNumber | | | +| **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 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 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 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 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 | @@ -38,4 +38,4 @@ -#### Note: If the usage in an API is already using a developer friendly term, the last column can be left blank. +#### Note: If the usage in an API is already using a developer-friendly term, the last column can be left blank. diff --git a/documentation/Issue and PR template Howto.md b/documentation/Issue and PR template Howto.md index 5cf487a9..09c4dcd4 100644 --- a/documentation/Issue and PR template Howto.md +++ b/documentation/Issue and PR template Howto.md @@ -2,7 +2,7 @@ ## Introduction -GitHub enables using templates in order to customize and standardize the information contributors +GitHub enables using templates to customize and standardize the information contributors include when they open issues and pull requests in the repository. The proposed set of templates is adjusted to be applicable mainly to CAMARA API specification subprojects. @@ -14,13 +14,13 @@ GitHub uses templates for the repository if the respective template configuratio ## Configuration -In order to use templates for issues and pull request for the CAMARA Subproject the following steps need to be taken: +To use templates for issues and pull request for the CAMARA Subproject, the following steps need to be taken: -1. Copy the folder [.github](https://github.com/camaraproject/Commonalities/tree/main/artifacts/Github_templates/.github) +1.) Copy the folder [.github](https://github.com/camaraproject/Commonalities/tree/main/artifacts/Github_templates/.github) to the root of Subproject repository. -2. Edit the `config.yml` file inside `.github/ISSUE_TEMPLATE/` folder: -* to allow creating blank issues (without template) set: +2.) Edit the `config.yml` file inside `.github/ISSUE_TEMPLATE/` folder: +* to allow creating blank issues (without a template) set: ``` blank_issues_enabled: true ``` @@ -31,7 +31,7 @@ blank_issues_enabled: true url: https://github.com/camaraproject/Commonalities/discussions about: Please ask and answer questions here. ``` -3. Modify Issue and PR templates in Markdown files included in the `.github` folder if needed. +3.) Modify Issue and PR templates in Markdown files included in the `.github` folder if needed. * Issue templates include headers, where the name and description of issue category, the suggested title of the issue, the labels and assignees for the issue can be configured, e.g. @@ -46,37 +46,37 @@ assignees: '' ``` ## Usage -Templates are automatically imported when creating new issue or PR via Github web interface. +Templates are automatically imported when creating new issue or PR via GitHub web interface. ### Issue templates -Github allows to multiple templates to be used for creating issues. -The screenshot below presents available options with proposed set of templates and configs: +GitHub allows multiple templates to be used for creating issues. +The screenshot below presents available options with a proposed set of templates and configs: ![](images/New%20Issue%20%C2%B7%20templates.png) -Note, that **Report a security vulnerability** option is added by Github and opening blank issues is enabled. -Preconfigured external links (here: Subproject discussions, CAMARA API Design Guidelines) will be opened in new tab of the browser. +Note that **Report a security vulnerability** option is added by GitHub and opening blank issues is enabled. +Preconfigured external links (here: Subproject discussions, CAMARA API Design Guidelines) will be opened in new tab of the browser. -The proposed issue categories are prepared with Github labels: +The proposed issue categories are prepared with GitHub labels: -|Category| Description|Labels| -|---|---|---| -|Bug| Describing bugs in Provider Implementations|_implementation:bug_ | -|Correction|Suggesting corrections of API specification or indicating misalignment with API design guidelines|_correction_ | -|Documentation| Indicating issues with API documentation or supplementary documents| _documentation_ | -|Enhancement| Suggesting ideas for new API features or questions on directions for API evolution| _enhancement_ | -|Subproject management| Indicating issues with subproject repository or release management process|_subproject management_ | -|Tests | Indicating issues with API tests | _tests_ | +| Category | Description | Labels | +|-----------------------|---------------------------------------------------------------------------------------------------|-------------------------| +| Bug | Describing bugs in Provider Implementations | _implementation:bug_ | +| Correction | Suggesting corrections of API specification or indicating misalignment with API design guidelines | _correction_ | +| Documentation | Indicating issues with API documentation or supplementary documents | _documentation_ | +| Enhancement | Suggesting ideas for new API features or questions on directions for API evolution | _enhancement_ | +| Subproject management | Indicating issues with subproject repository or release management process | _subproject management_ | +| Tests | Indicating issues with API tests | _tests_ | ### Pull request template -Pull request template is based on the template use in [Kubernetes project](https://github.com/kubernetes/kubernetes/blob/master/.github/PULL_REQUEST_TEMPLATE.md) +Pull request template is based on the template used in [Kubernetes project](https://github.com/kubernetes/kubernetes/blob/master/.github/PULL_REQUEST_TEMPLATE.md) -It requires to indicate kind of PR as one of: +It requires indicating kind of PR as one of: * bug * correction * enhancement/feature @@ -88,7 +88,7 @@ It requires to indicate kind of PR as one of: The proposed above values correspond to issue categories, with additional type: _cleanup_ for simple correction of typos/spelling mistakes or application of guidelines. After describing what the PR does, the link to relevant issue should be added. -Thanks to Github keywords: `Fixes #`, or `Fixes (paste link of issue)` pull request is linked to relevant issue to show that a fix is in progress and to automatically close the issue when the pull request is merged. +Thanks to GitHub keywords: `Fixes #`, or `Fixes (paste link of issue)` pull request is linked to relevant issue to show that a fix is in progress and to automatically close the issue when the pull request is merged. The pull request template includes the place to input a clear, concise description of the change that will facilitate creation of the **Release Notes**. @@ -96,6 +96,6 @@ The pull request template includes the place to input a clear, concise descripti ## References [Github templates documentation](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates) -[Github keywords to link an issue and pull request](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests) +[GitHub's keywords to link an issue and pull request](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests) [Full Emoji List](https://unicode.org/emoji/charts/full-emoji-list.html) diff --git a/documentation/Linting-rules.md b/documentation/Linting-rules.md index 625a9694..8b4d39b7 100644 --- a/documentation/Linting-rules.md +++ b/documentation/Linting-rules.md @@ -7,15 +7,16 @@ Spectral has a built-in OpenAPI Specification ruleset that can be used to validate OpenAPI files. -With `extends: "spectral:oas"` ("oas" being shorthand for OpenAPI Specification) in the ruleset file to rules for OpenAPI v2 and v3.x, depending on the appropriate OpenAPI version being used (this is automatically detected through formats) are added to the final ruleset. +With `extends: "spectral:oas"` ("oas" being shorthand for OpenAPI Specification) in the ruleset file to rules for OpenAPI v2 and v3.x, depending on the appropriate OpenAPI version being used (this is automatically detected through formats) is added to the final ruleset. -All of the rules in this ruleset are described in [OpenAPI Rules](https://docs.stoplight.io/docs/spectral/4dec24461f3af-open-api-rules). +All the rules in this ruleset are described in [OpenAPI Rules](https://docs.stoplight.io/docs/spectral/4dec24461f3af-open-api-rules). -`extends: [[spectral:oas, off]]` - this avoids running any rules from the extended ruleset as they are disabled. Each rule then can be [enabled individually](https://docs.stoplight.io/docs/spectral/0a73453054745-recommended-or-all#enabling-rules). +`extends: [[spectral:oas, off]]` - This avoids running any rules from the extended ruleset as they are disabled. Each rule then can be [enabled individually](https://docs.stoplight.io/docs/spectral/0a73453054745-recommended-or-all#enabling-rules). + ### Recommended rules -Spectral's built-in OpenAPI ruleset is a two-tier system: with subset of rules marked as [recommended](https://docs.stoplight.io/docs/spectral/0a73453054745-recommended-or-all#recommended-or-all) to be used by default, and addtional rules marked with `recommended: false`. +Spectral's built-in OpenAPI ruleset is a two-tier system: with subset of rules marked as [recommended](https://docs.stoplight.io/docs/spectral/0a73453054745-recommended-or-all#recommended-or-all) to be used by default, and additional rules marked with `recommended: false`. Recommended rules cover more basic requirements. ### Rule severity @@ -25,54 +26,54 @@ The default value is `warn`. ### OpenAPI v2 & v3 -Rules applying to both OpenAPI v2.0, v3.0, and most likely v3.1 - details are described in [Spectral Documentation](https://docs.stoplight.io/docs/spectral/4dec24461f3af-open-api-rules#openapi-v2--v3). - -|Name| Desc| Recom mended|CAMARA use|Spectral severity | CAMARA severity | -|---|---|---|--|---|--| -|contact-properties| contact object is full of the most useful properties: `name`, `url`, and `email`| No | No | Warning | Warning | -|duplicated-entry-in-enum| Each value of an `enum` must be different from one another | Yes | Yes | Warning | Warning | -|info-contact |Info object should contain `contact` object |Yes | Yes | Warning | Warning | -|info-description |Info object should contain `description` object | Yes | Yes| Warning | Warning | -|info-license |Info object should contain `license` object |Yes | Yes | Warning | Warning | -|license-url | link to the full text of licence | Yes | Yes| Warning | Warning | -|no-$ref-siblings| Before OpenAPI v3.1, keywords next to $ref were ignored | Yes | Yes| Error | Error | -|no-eval-in-markdown | injecting `eval()` JavaScript statements could lead to an XSS attack | Yes | Yes | Warning | Warning | -|no-script-tags-in-markdown | injecting `