diff --git a/APIBacklog/documentation/SupportingDocuments/others/capabilities/camara-capability-api-v0.4.2.yaml b/APIBacklog/documentation/SupportingDocuments/others/capabilities/camara-capability-api-v0.4.2.yaml
new file mode 100644
index 00000000..b81f8081
--- /dev/null
+++ b/APIBacklog/documentation/SupportingDocuments/others/capabilities/camara-capability-api-v0.4.2.yaml
@@ -0,0 +1,820 @@
+openapi: 3.0.3
+info:
+ title: CAMARA Generic Capability API
+ description: |
+ The CAMARA Capability API provides programmable interface for developers and other users (capabilities consumers) to discover and be notified
+ about active capabilities (functions) for APIs.
+
+ # Introduction
+ This API enables feature discovery and real-time feature status notifications for APIs provided by the gateway.
+
+ An **API** (Application Programming Interface) often includes **features** that can be *active* or *inactive* during
+ interactions with API consumers. For example, feature negotiation during session establishment or events such as high congestion that
+ change a feature's status.
+
+ **Capabilities** represent a collection of features and their **status** (*active* or *inactive*) at a specific point in time.
+ These capabilities provide a way to describe what an API can do.
+
+ **Footprints** define the coverage area where specific capabilities are available. A device must be located within the footprint to access
+ these capabilities. If no footprint is specified, the capabilities *may* be available to *any* device connected to the network. Footprints
+ have a *usage type* that determines their visibility and use. For example, some footprints may only be visible to Access Networks where
+ devices are attached, while others may be visible to Internet servers or services in a Non-Access network. Some footprints
+ may even be used in both types of networksd.
+
+ When footprints are used, they are presented as part of a collection. A device is considered to be covered by a footprint collection if it
+ falls within at least one footprint in the collection. Footprint *precedence* specifies the search execution order of footprints in the
+ collection. The lower the numerical value of precedence, the higher the footprint precedence. Footprints with equal precedence MAY be
+ executed in parallel if supported by the sytem.
+
+ **Resource Scopes** are URIs that further restrict when capabilites apply. These scopes may refer to one or more device sessions,
+ specific times of day and other relevant conditions.
+
+ **Footprints** and **Resource Scopes** help define conditions under which the capabilities are relevant. For a capability to be usable,
+ all required Footprints and Resource Scopes must be satisfied (see *Usage* for more detail).
+
+ To convey the impact of capability status to API consumers in a meaningful way, capabilities are directly tied to a set of **Runtime Restrictions**.
+ These restrictions affect optional or alternative structures, parameters, and other aspects of API usage.
+
+ **Capabilties Set** associates a **Footprints** and **Resource Scopes** to **Capabilties** using a *group type* mechanism. The grouping type may be
+ the organizations that defined the capabilities, an operator, etc.
+
+ **Bit Sets** are used to efficiently communicate capability status. In a Bit Set, individual bits represent the active (1) or
+ inactive (0) status of specific **Capability Sets**. Bit Sets may also include a **Footprints** or **Resource Scopes** to further
+ define the applicability of the status.
+
+ If both the Bit Set and a specific Capability Set provide Footprints, the Device must satisfy the conditions of both Footprints
+ collections and Resource Scopes for the bit’s status to be applicable. To avoid conflicts where a capability is active in one bit
+ while inactive in another, Bit Sets have a concept of correctness or well-formedness. Each Capability across all Bit Sets must not
+ appear with overlapping Footprints, the same major/minor versions, and overlapping Resource Scopes.
+
+ # Usage
+ API Consumers first use a GET operation to acquire **Capability Bit Set Specifications**, which include the *Capability Sets* and
+ associated *Footprints* and *Runtime Restrictions Set Identifiers*. With these definitions, API Consumers can then use a GET operation to acquire **Capabilities Bit Set Values**
+ which contain the *current* bit status of associated **Capability Bit Sets**. API Consumers may choose to acquire all Bit Set Values or
+ specific ones. Additionally, API Consumers may acquire the URL of the **Capability Notification Server** to subscribe to subsequent
+ changes in *Capabilities, Capabilities Set, Capability Bit Sets or Capability Bit Set* values. Three event types are supported
+
+ - BitSetRemovedEvent includes the Capabilities Bit Set that has been removed.
+
- BitSetChangedEvent includes the changed event. In this event the name of BitSet indicates
+ the target BitSet but its version will be changed. If a cacheId is included, it may be used to indicate the BitSet
+ that will be updated. Any new references to the cacheId will use the event's BitSet as its target.
+
- BitSetValueChangedEvent indicates that the BitSet value has changed.
+
+
+
+ # Relevant terms and definitions
+
+ * **Authentication**:
+ Security access keys such as OAuth 2.0 client credentials used by client applications to invoke the Capability API.
+
+ * **API (Application Programming Interface)**:
+ A set of protocols and tools for building software and applications.
+
+ * **Features**:
+ Specific functions or capabilities of an API that can be active or inactive.
+
+ * **Capabilities**:
+ A collection of features and their status (active or inactive) at a specific point in time.
+
+ * **Footprints**:
+ Define the coverage area where specific capabilities are available.
+
+ * **Resource Scopes**:
+ URIs that further restrict when capabilities apply.
+
+ * **Runtime Restrictions**:
+ Restrictions that affect optional or alternative structures, parameters, and other aspects of API usage.
+
+ * **Capabilities Set**:
+ Associates a Footprint and Resource Scopes to Capabilities using a group type mechanism.
+
+ * **Bit Sets**:
+ Used to efficiently communicate capability status, where individual bits represent the active (1) or inactive (0) status of specific Capability Sets.
+
+ # API functionality
+
+ Please see examples within this yaml on what options the gateway may return in the response.
+
+ # Further info and support
+
+ ## Frequently Asked Questions (FAQs)
+
+ 1. What is the purpose of the API described in the text? The API enables feature discovery and real-time feature status notifications
+ for APIs provided by the gateway.
+
+ 2. What are capabilities and how do they relate to API features? Capabilities represent a collection of features and their
+ status (active or inactive) at a specific point in time. These capabilities provide a way to describe what an API can do.
+
+ 3. What are footprints and how do they affect the availability of capabilities? Footprints define the coverage area where specific
+ capabilities are available. A device must be located within the footprint to access these capabilities. If no footprint is specified,
+ the capabilities may be available to any device connected to the network.
+
+ 4. How do resource scopes restrict the applicability of capabilities? Resource Scopes are URIs that further restrict when capabilities
+ apply. These scopes may refer to one or more device sessions, specific times of day, and other relevant conditions.
+
+ 5. What is the role of footprint precedence in the search execution order? Footprint precedence specifies the search execution order of
+ Footprints in the collection. The lower the numerical value of precedence, the higher the Footprint precedence. Footprints with equal
+ precedence may be executed in parallel if supported by the system.
+
+ 6. How do runtime restrictions affect API usage? To convey the impact of capability status to API consumers in a meaningful way,
+ capabilities are directly tied to a set of runtime restrictions. These restrictions affect optional or alternative structures,
+ parameters, and other aspects of API usage.
+
+ 7. What is a Capabilities Set and how is it associated with Footprints and Resource Scopes? A Capabilities Set associates a Footprint
+ and Resource Scopes to Capabilities using a group type mechanism. The grouping type may be the organizations that defined the
+ capabilities, an operator, etc.
+
+ 8. How are Bit Sets used to communicate capability status? Bit Sets are used to efficiently communicate capability status. In a Bit Set,
+ individual bits represent the active (1) or inactive (0) status of specific Capability Sets. Bit Sets may also include a Footprint or
+ Resource Scopes to further define the applicability of the status.
+
+ 9. How do Bit Sets and Capability Sets interact with Footprints and Resource Scopes? If both the Bit Set and a specific Capability Set
+ provide Footprints, the Device must satisfy the conditions of both Footprint collections and Resource Scopes for the bit’s status to
+ be applicable. To avoid conflicts where a capability is active in one bit while inactive in another, Bit Sets have a concept of
+ correctness or well-formedness.
+
+ 10. How do API Consumers acquire Capability Set Specifications and Bit Set Values? API Consumers first use a GET operation to acquire
+ Capability Set Specifications, which include the Capability Sets and associated Footprints and Runtime Restrictions Set Identifiers.
+ With these definitions, API Consumers can then use a GET operation to acquire Capabilities Bit Set Values which contain the current
+ bit status of associated Capability Bit Sets. API Consumers may choose to acquire all Bit Set Values or specific ones. Additionally,
+ API Consumers may acquire the URL of the Capability Notification Server to subscribe to subsequent changes in Capabilities,
+ Capabilities Set, Capability Bit Sets or Capability Bit Set values.
+ termsOfService: http://swagger.io/terms/
+ contact:
+ email: project-email@sample.com
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.4.2-wip
+externalDocs:
+ description: Product documentation at Camara
+ url: https://github.com/camaraproject/
+security:
+ - oAuth2ClientCredentials: []
+servers:
+ - url: "{apiRoot}/{basePath}"
+ variables:
+ apiRoot:
+ default: http://localhost:9091
+ description: API root
+ basePath:
+ default: cap/v0
+ description: Base path for the CAMARA Capability API
+paths:
+ /cap-notification-server:
+ get:
+ tags:
+ - Notification Server URL
+ summary: |
+ Query the notification server URL for the capabilities API provider.
+ description: |
+ Returns the notification server URL for the capabilities API provider. This will be returned with HTTP Status Code 301 (Moved Permanently).
+ Code 301 is used instead of 302 (Temporary) to ensure the Client does not need to repeatedly poll this path. The Notificxation's URL
+ is returned as part of the Location Header.
+ operationId: getCapabilitiesApiNotificationServerURL
+ responses:
+ "301":
+ description: Contains information about the notification server location
+ headers:
+ Location:
+ schema:
+ type: string
+ example: "https://api-provider.example.com/subscriptions"
+ "401":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Unauthenticated"
+ "403":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/PermissionDenied"
+ "500":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Internal"
+ "503":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Unavailable"
+ security:
+ - oAuth2ClientCredentials: []
+ - threeLegged:
+ - "cap-notification-server-read"
+ options:
+ tags:
+ - Get Notification Server URL Features
+ operationId: getCapNotificatServerFeatures
+ description: Discover supported features and methods for this endpoint
+ responses:
+ "200":
+ description: OK
+ headers:
+ Allow:
+ schema:
+ type: string
+ default: "GET,OPTIONS"
+ security:
+ - oAuth2ClientCredentials: []
+ - threeLegged:
+ - "cap-notification-server-read"
+ /bitsets:
+ get:
+ tags:
+ - Get All Bitsets
+ summary: "Query bit set values for all service capabilities on the gateway"
+ description: |
+ Returns the set of bitset values for all service capabilities on the gateway.
+ operationId: getBitsetValues
+ responses:
+ "200":
+ description: Contains all BitSet values
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: "#/components/schemas/BitSetValue"
+ links:
+ GetFirstBitsetById:
+ operationId: getBitsetValuesByIdVersion
+ parameters:
+ name: '$response.body#/[0]/name'
+ version: '$response.body#/[0]/version'
+ "401":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Unauthenticated"
+ "403":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/PermissionDenied"
+ "404":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/NotFound"
+ "500":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Internal"
+ "503":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Unavailable"
+ security:
+ - oAuth2ClientCredentials: []
+ - threeLegged:
+ - "cap-bitvalue-read"
+ options:
+ tags:
+ - Get All Bitsets Features
+ operationId: getBitsetsFeatures
+ description: Discover supported features and methods for this endpoint
+ responses:
+ "200":
+ description: OK
+ headers:
+ Allow:
+ schema:
+ type: string
+ default: "GET,OPTIONS"
+ security:
+ - oAuth2ClientCredentials: []
+ - threeLegged:
+ - "cap-bitvalue-read"
+ /bitsets/{name}:
+ get:
+ tags:
+ - Get All Bitsets with the same name
+ summary: "Get all bitsets with the same name on the gateway"
+ description: |
+ Returns bitsets that matches the given name.
+ operationId: getBitsetValuesByName
+ parameters:
+ - name: name
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ "200":
+ description: Contains all BitSet value based on the name provided in the query.
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: "#/components/schemas/BitSetValue"
+ "401":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Unauthenticated"
+ "403":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/PermissionDenied"
+ "404":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/NotFound"
+ "500":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Internal"
+ "503":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Unavailable"
+ security:
+ - oAuth2ClientCredentials: []
+ - threeLegged:
+ - "cap-bitvalue-read"
+ options:
+ tags:
+ - Get Bitsets By Name Features
+ operationId: getBitsetsByNameFeatures
+ description: Discover supported features and methods for this endpoint
+ parameters:
+ - name: name
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ "200":
+ description: OK
+ headers:
+ Allow:
+ schema:
+ type: string
+ default: "GET,OPTIONS"
+ security:
+ - oAuth2ClientCredentials: []
+ - threeLegged:
+ - "cap-bitvalue-read"
+ /bitset-specifications:
+ get:
+ tags:
+ - Get all BitSet Specifications
+ summary: "Get all BitSet Specifications"
+ description: |
+ Returns all BitSet Specifications
+ operationId: getBitSetSpecifications
+ responses:
+ "200":
+ description: Contains an array of Bitset specifications
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: "#/components/schemas/CapabilitiesBitSetSpecification"
+ example:
+ OperatorAQoDrr:
+ description: operator A QoD related runtime restrictions
+ value:
+ {
+ name: "operator-a:qod-api:1.0",
+ version: "1.0.0",
+ cacheId: "Set1",
+ bitSet:
+ {
+ "0":
+ {
+ name: "operator-a:qod-api-rr-b0",
+ version: "0.0.1",
+ groupType: "org:operator-a:qod",
+ capabilities:
+ {
+ {
+ name: "operator-a:qod-api-rr-c135",
+ version: "0.0.1",
+ groupType: "org:operator-a:qod",
+ capDescription: "QoD runtime restrictions (1,3,5) defined as bit 0"
+ }
+ },
+ runtimeRestrictionsIDSet: [
+ "AcceptedDeviceIdentifiers",
+ "CreateSessionOperationNotSupported",
+ "SupportedScopesPerAuthFlow1"
+ ],
+ footprints:
+ {
+ {
+ name: "fp1",
+ version: "0.0.1",
+ footprintType: "itue212countrynetworkcode",
+ footprintValue: { "310120" },
+ }
+ }
+ },
+ "1":
+ {
+ name: "operator-a:qod-api-rr-b1",
+ version: "0.0.1",
+ groupType: "org:operator-a:qod",
+ capabilities:
+ {
+ {
+ name: "operator-a:qod-api-rr-c246",
+ version: "0.0.1",
+ groupType: "org:operator-a:qod",
+ capDescription: "QoD runtime restrictions (2,4,6) defined as bit 1"
+ }
+ },
+ runtimeRestrictionsIDSet: [
+ "OfferedQoSProfiles",
+ "LocationRadiusRange",
+ "SupportedScopesPerAuthFlow2"
+ ],
+ footprints:
+ {
+ {
+ name: "fp2",
+ version: "0.0.1",
+ footprintType: "geographicaddress",
+ footprintValue: { "Bellevue, WA" }
+ }
+ }
+ },
+ "2":
+ {
+ name: "operator-a:qod-api-rr-b2",
+ version: "0.0.1",
+ groupType: "org:operator-a:qod",
+ capabilities:
+ {
+ {
+ name: "operator-a:qod-api-rr-c246",
+ version: "0.0.1",
+ groupType: "org:operator-a:qod",
+ capDescription: "QoD runtime restrictions (2,4,6) at Bellevue WA area defined as bit 2"
+ }
+ },
+ runtimeRestrictionsIDSet: [
+ "OfferedQoSProfiles",
+ "LocationRadiusRange",
+ "ServingAreaBellevueWARadius",
+ "ServingAreaBellevueWALatitude",
+ "ServingAreaBellevueWALongitude",
+ "SupportedScopesPerAuthFlow2"
+ ],
+ footprints:
+ {
+ {
+ name: "fp3",
+ version: "0.0.1",
+ footprintType: "geographicaddress",
+ footprintValue: { "Bellevue, WA" }
+ }
+ }
+ },
+ "3":
+ {
+ name: "operator-a:qod-api-rr-b3",
+ version: "0.0.1",
+ groupType: "org:operator-a:qod",
+ capabilities:
+ {
+ {
+ name: "operator-a:qod-api-rr-c246",
+ version: "0.0.1",
+ groupType: "org:operator-a:qod",
+ capDescription: "QoD runtime restrictions (2,4,6) for a group of specific QoD sessions in Bellevue WA area defined as bit 3"
+ }
+ },
+ runtimeRestrictionsIDSet: [
+ "OfferedQoSProfiles",
+ "LocationRadiusRange",
+ "ServingAreaBellevueWARadius",
+ "ServingAreaBellevueWALatitude",
+ "ServingAreaBellevueWALongitude",
+ "SupportedScopesPerAuthFlow2"
+ ],
+ footprints:
+ {
+ {
+ name: "fp3",
+ version: "0.0.1",
+ footprintType: "geographicaddress",
+ footprintValue: { "Bellevue, WA" }
+ }
+ },
+ resourceScopes: [
+ "https://api.example.com/qod/v0/sessions/123a4567-e89b-12d3-a456-426614174000",
+ "https://api.example.com/qod/v0/sessions/123b4567-e89b-12d3-a456-426614174001",
+ "https://api.example.com/qod/v0/sessions/123c4567-e89b-12d3-a456-426614174002"
+ ]
+ }
+ }
+ }
+ "401":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Unauthenticated"
+ "403":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/PermissionDenied"
+ "404":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/NotFound"
+ "500":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Internal"
+ "503":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Unavailable"
+ security:
+ - oAuth2ClientCredentials: []
+ - threeLegged:
+ - "cap-bitdefinition-read"
+ options:
+ tags:
+ - Get all BitSet Specifications Features
+ operationId: getBitsetsSpecificationsFeatures
+ description: Discover supported features and methods for this endpoint
+ responses:
+ "200":
+ description: OK
+ headers:
+ Allow:
+ schema:
+ type: string
+ default: "GET,OPTIONS"
+ security:
+ - oAuth2ClientCredentials: []
+ - threeLegged:
+ - "cap-bitdefinition-read"
+
+components:
+ securitySchemes:
+ oAuth2ClientCredentials:
+ description: |
+ The Capability API makes use of the OAUTH 2.0 client credentials grant which is applicable for server to server use cases involving trusted partners or clients without any protected user data involved.
+ In this method the API invoker client is registered as a confidential client with an authorization grant type of client_credentials
+ type: oauth2
+ flows:
+ clientCredentials:
+ tokenUrl: https://api.example.com/oauth/token
+ scopes: {}
+ threeLegged:
+ type: oauth2
+ description: This API uses OAuth 2 with the authorization code grant flow.
+ flows:
+ authorizationCode:
+ authorizationUrl: https://api.example.com/oauth2/authorize
+ tokenUrl: https://api.example.com/oauth/token
+ scopes:
+ cap-notification-server-read: Retrieval of Capabilities API provider notification server
+ cap-bitvalue-read: Retrieval of BitSetValue
+ cap-bitdefinition-read: Retrieval of CapabilitiesBitSetSpecification
+
+ schemas:
+ VersionedName:
+ description: |
+ An abstract base object containing names with versioning, seperated by :
+ type: object
+ properties:
+ name:
+ description: The item's name. Ideally, it is a unique value for its type. This value MUST NOT contain the semicolon - ';'
+ type: string
+ example:
+ capabilties: "cap1"
+ footprints: "fp1"
+ minLength: 3
+ maxLength: 256
+ pattern: "^[^;]*$"
+ version:
+ description: The version of the object instance.
+ type: string
+ example: "0.0.1"
+ minLength: 1
+ required:
+ - name
+ - version
+
+ GroupType:
+ description: Used to separate groups of capabilities by type, specifcation body, etc.
+ example:
+ threegpptypes: "org:3gpp"
+ camaraqodcapabilities: "org:camara:qod"
+ operatorqodcapabilities: "operator-a:qod"
+ georestrictionzonea: "zonea:restrictions"
+ type: string
+ minLength: 1
+
+ Capability:
+ description: |
+ A feature or set of features of a system. A Capability can be enabled/disabled via various mechanisms. Capabilities are versioned
+ and may contain a GroupType for grouping of similar capabilities.
+ allOf:
+ - $ref: "#/components/schemas/VersionedName"
+ - type: object
+ properties:
+ groupType:
+ $ref: "#/components/schemas/GroupType"
+ capDescription:
+ description: Description of the capability.
+ type: string
+ minLength: 1
+ required:
+ - groupType
+
+ Footprint:
+ description: |
+ The coverage area to which capabilties apply. They help define the context in which the features are relevant.
+ There are many ways to describe a footprint -- for example, by address range (e.g., IPv4 CIDR or IPv6 CIDR (Classless Inter-Domain Routing),
+ network ID (e.g., Autonomous System Number (ASN)), nation boundaries (e.g., country code) or GPS coordinates.
+
+ When a **Footprint** value is not present, the capabilities apply to *any* connected device.
+ allOf:
+ - $ref: "#/components/schemas/VersionedName"
+ - type: object
+ properties:
+ footprintType:
+ description: |
+ Types include:
+ * Content Delivery Network Interconnection types
+ * Geo postion types
+ * Civic Address types
+ * Geographic Address type types
+ * Geographic Location type types
+ * Geographic Site type types
+ * ITU E.212 Mobile Country Code and Mobile Network Code values
+ * GeoJSON
+ * TopoJSON
+ type: string
+ enum:
+ - ipv4cidr
+ - ipv6cidr
+ - asn
+ - countrycode
+ - altopid
+ - subdivisioncode
+ - footprintunion
+ - civickaddress
+ - geoposition
+ - itue212countrynetworkcode
+ - postaladdress
+ - geographicaddress
+ - geographiclocation
+ - geographicsite
+ - geojson
+ - topojson
+ footprintValue:
+ description: A list of footprint values.
+ type: array
+ items:
+ oneOf:
+ - type: string
+ - type: object
+ - type: array
+ footprintUsage:
+ description: Indicates that the footprint value represents an Access Network, a non Access Network, i.e., networks facing the Internet, or both.
+ type: string
+ enum:
+ - access
+ - non_access
+ - both
+ precedence:
+ description: |
+ Specifies the search execution order of Footprints when they are part of a collection. The lower the numerical value of precedence,
+ the higher the rule precedence. Rules with equal precedence MAY be executed in parallel if supported.
+ type: integer
+ minimum: 0
+ required:
+ - name
+ - version
+ - footprintType
+ - footprintValue
+ - footprintUsage
+ - precedence
+
+ CapabilitiesSet:
+ description: A set of capabilties of the same groupType. The set may be restricted by a Footprint. A *well formed*
+ allOf:
+ - $ref: "#/components/schemas/VersionedName"
+ - type: object
+ properties:
+ groupType:
+ $ref: "#/components/schemas/GroupType"
+ capabilities:
+ description: The set of capablity versioned name pairs.
+ type: array
+ items:
+ $ref: "#/components/schemas/Capability"
+ minItems: 1
+ runtimeRestrictionsIDSet:
+ description: |
+ An array of references to the response of RR
+ identifiers
+ within a successful Runtime Restrictions API response
+ type: array
+ items:
+ type: string
+ minItems: 1
+ footprints:
+ type: array
+ items:
+ $ref: "#/components/schemas/Footprint"
+ resourceScopes:
+ description: |
+ Optional list of resource identifiers this **CapabilitiesSet** is constrainted to. Each resource identifier is a $ref field of the path item object in the OAS.
+ If resourceScope is not present, the **CapabilitieSet** applies to all resources within the applicable **Footprints**.
+ The example shows this set of capabilities only applies to a specified QoD session.
+ type: array
+ items:
+ type: string
+ example: "https://api.example.com/qod/v0/sessions/123e4567-e89b-12d3-a456-426614174000"
+ required:
+ - name
+ - version
+ - groupType
+ - capabilities
+ - runtimeRestrictionsIDSet
+
+ CacheId:
+ description: |
+ A cache identifier. This is a unique key for management of updates between the API provider and Consumers. When this value is not provided, cache management,
+ if provided, occurs via implementation specific means.
+ type: string
+ minLength: 1
+
+ CapabilitiesBitSetSpecification:
+ description: A collection of capabilities. It maintains a mapping (integer => CapabiltiesSet) that descrbes the capabilities in this set.
+ allOf:
+ - $ref: "#/components/schemas/VersionedName"
+ - type: object
+ properties:
+ cacheId:
+ $ref: "#/components/schemas/CacheId"
+ bitSet:
+ description: |
+ A map of capability bit positions (postitive integeres) as a Swagger 3.0.3 Dictionary. The keys (attribute names)
+ specify the bit positions for the capability and MUST be positive integers and unqiue to the bitSet map. Any other key type will be ignored.
+ type: object
+ additionalProperties:
+ $ref: '#/components/schemas/CapabilitiesSet'
+ footprints:
+ type: array
+ items:
+ $ref: "#/components/schemas/Footprint"
+ resourceScopes:
+ description: |
+ Optional list of resource identifiers this **CapabilitiesSet** is constrainted to. Each resource identifier is a $ref field of the path item object in the OAS.
+ If resourceScope is not present, the **CapabilitieSet** applies to all resources within the applicable **Footprints**.
+ The example shows this set of capabilities only applies to a specified QoD session.
+ type: array
+ items:
+ type: string
+ example: "https://api.example.com/qod/v0/sessions/123e4567-e89b-12d3-a456-426614174000"
+ required:
+ - cacheId
+ - bitSet
+
+ BitSetValue:
+ description: |
+ A bit vector value for the referenced Capability Set (as indicated by the name/version properties xor cacheId).
+ allOf:
+ - $ref: "#/components/schemas/VersionedName"
+ - type: object
+ properties:
+ cacheId:
+ $ref: "#/components/schemas/CacheId"
+ vectorValue:
+ description: A BitSetValue value. It is a hexdcimal string.
+ type: string
+ format: string
+ pattern: "^[0-9A-Fa-f]+$"
+ example: "1"
+ oneOf:
+ - required:
+ - vectorValue
+ - cacheId
+ - required:
+ - vectorValue
+ - name
+ - version
+
+ BitSetValueChangedEvent:
+ description: BitSet Value Changed cloud event.
+ allOf:
+ - $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/camara-cloud-event-common-v1.0.yaml#/components/CloudEventBase"
+ - type: object
+ properties:
+ data:
+ description: 'event details payload described in each CAMARA API and referenced by its "type"'
+ allOf:
+ - $ref: "#/components/schemas/BitSetValue"
+ - type: object
+ properties:
+ subscriptionId:
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/camara-cloud-event-common-v1.0.yaml#/components/SubscriptionId"
+
+ BitSetRemovedEvent:
+ description: BitSet Removed cloud event.
+ allOf:
+ - $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/camara-cloud-event-common-v1.0.yaml#/components/CloudEventBase"
+ - type: object
+ properties:
+ data:
+ description: 'event details payload described in each CAMARA API and referenced by its "type"'
+ allOf:
+ - $ref: "#/components/schemas/CapabilitiesBitSetSpecification"
+ - type: object
+ properties:
+ subscriptionId:
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/camara-cloud-event-common-v1.0.yaml#/components/SubscriptionId"
+
+ BitSetChangedEvent:
+ description: BitSet Changed cloud event.
+ allOf:
+ - $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/camara-cloud-event-common-v1.0.yaml#/components/CloudEventBase"
+ - type: object
+ properties:
+ data:
+ description: 'event details payload described in each CAMARA API and referenced by its "type"'
+ allOf:
+ - $ref: "#/components/schemas/CapabilitiesBitSetSpecification"
+ - type: object
+ properties:
+ subscriptionId:
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/camara-cloud-event-common-v1.0.yaml#/components/SubscriptionId"
+
+ CapabilityEvents:
+ description: Capabilty API Events.
+ oneOf:
+ - $ref: "#/components/schemas/BitSetValueChangedEvent"
+ - $ref: "#/components/schemas/BitSetRemovedEvent"
+ - $ref: "#/components/schemas/BitSetChangedEvent"
+ discriminator:
+ propertyName: type
+ mapping:
+ "org.camara.capability.0.4.1.BitSetValueChangedEvent": "#/components/schemas/BitSetValueChangedEvent"
+ "org.camara.capability.0.4.1.BitSetRemovedEvent": "#/components/schemas/BitSetRemovedEvent"
+ "org.camara.capability.0.4.1.BitSetChangedEvent": "#/components/schemas/BitSetChangedEvent"
diff --git a/APIBacklog/documentation/SupportingDocuments/others/capabilities/camara-cloud-event-common-v1.0.yaml b/APIBacklog/documentation/SupportingDocuments/others/capabilities/camara-cloud-event-common-v1.0.yaml
new file mode 100644
index 00000000..64b5bbb9
--- /dev/null
+++ b/APIBacklog/documentation/SupportingDocuments/others/capabilities/camara-cloud-event-common-v1.0.yaml
@@ -0,0 +1,81 @@
+openapi: 3.0.3
+info:
+ title: CAMARA Notification as Cloud Event Common Structures
+ description: Common data structures for Notification as Cloud Event
+ termsOfService: http://swagger.io/terms/
+ contact:
+ email: project-email@sample.com
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.1.6-wip
+externalDocs:
+ description: Product documentation at Camara
+ url: https://github.com/camaraproject/
+components:
+ schemas:
+ SubscriptionId:
+ description: Identifier of the event subscription - This attribute must not be present in the POST request as it is provided by API server.
+ Applies to Resource-based (explicit) subscription. This value is mandatory in server response.
+ type: string
+ minLength: 1
+
+ #Cloud Event structures
+ DateTime:
+ type: string
+ format: date-time
+ description: Timestamp of when the occurrence happened. Must adhere to RFC 3339.
+ example: '2018-04-05T17:31:00Z'
+
+ Source:
+ type: string
+ format: uri-reference
+ minLength: 1
+ description: 'Identifies the context in which an event happened(example: "com.orange.camara.qod")'
+ example:
+ - https://github.com/cloudevents
+ - mailto:cncf-wg-serverless@lists.cncf.io
+ - urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66
+ - cloudevents/spec/pull/123
+ - /sensors/tn-1234567/alerts
+ - 1-555-123-4567
+
+ CloudEventBase:
+ description: 'The notification callback. This deviates from CloudEvents by requiring the "time" attribute.'
+ required:
+ - id
+ - source
+ - type_sne
+ - specversion
+ - time
+ properties:
+ id:
+ type: string
+ description: identifier of this event, that must be unique in the source context. It MUST be unique within the scope of the producer
+ minLength: 1
+ source:
+ $ref: '#/components/schemas/Source'
+ type:
+ type: string
+ description: 'type of event as defined in each CAMARA API (e.g.: org.camaraproject.qod.qos-status-changed-event)'
+ example: 'org.camaraproject.qod.qos-status-changed-event'
+ minLength: 25
+ specversion:
+ type: string
+ description: 'version of the specification to which this event conforms (must be "1.0" if it conforms to cloudevents 1.0.2 version)'
+ minLength: 3
+ datacontenttype:
+ type: string
+ description: 'media-type that describes the event payload encoding, must be "application/json" for CAMARA APIs'
+ time:
+ $ref: "#/components/schemas/DateTime"
+
+ DataEventBase:
+ description: Base stucture for the Data subtypes of cloud events.
+ properties:
+ data:
+ type: object
+ description: 'event details payload described in each CAMARA API and referenced by its "type"'
+ properties:
+ subscriptionId:
+ $ref: "#/components/schemas/SubscriptionId"
diff --git a/APIBacklog/documentation/SupportingDocuments/others/capabilities/camara-notification-api-v0.1.9.yaml b/APIBacklog/documentation/SupportingDocuments/others/capabilities/camara-notification-api-v0.1.9.yaml
new file mode 100644
index 00000000..9f40b05d
--- /dev/null
+++ b/APIBacklog/documentation/SupportingDocuments/others/capabilities/camara-notification-api-v0.1.9.yaml
@@ -0,0 +1,583 @@
+openapi: 3.0.3
+info:
+ title: CAMARA Subscription, Notification & Event (SNE) Common API
+ description: |
+ This is a common API implementation of the CAMARA Commonalities API Design Guidelines Subscription, Notification & Event section.
+
+
+ # Introduction
+ The CAMARA Subscription, Notification & Event (SNE) Common API provides a programmable interface for developers and other users to subscribe to events and receive notifications. This is a common API implementation of the CAMARA Commonalities API Design Guidelines Subscription, Notification & Event section. It supports implicit subscription structure (webhook) but it cannot define it - that is API specific.
+
+ # Subscribe to the API
+ To subscribe to the API, you will need to use the POST operation on the /subscriptions endpoint and provide the necessary information in the request body.
+
+ # API Authentication
+ Security access keys such as OAuth 2.0 client credentials are used by client applications to invoke the Notification API.
+
+ # API Description
+ ## Summary of resources
+ The CAMARA Subscription, Notification & Event (SNE) Common API provides several operations for managing event subscriptions, including creating, retrieving, and deleting subscriptions. The API provides several resources for managing event subscriptions, including the /subscriptions endpoint for creating, retrieving, and deleting subscriptions, and the /supportedEventTypes endpoint for retrieving a list of supported event types.
+
+ ## Supported Operations
+ ### **Create a subscription**
+ #### Summary of request body parameters
+ The request body must include a webhook object, which contains details for the event channel, such as the notification URL and the notification authentication token. The request body may also include a subscriptionExpireTime and a subscriptionDetail object.
+
+ ## Summary of response body parameters
+ The response body includes a subscriptionId value, which is a unique identifier for the event subscription. This value can be used to retrieve, update, or delete the subscription.
+
+ ## List of identifiers returned to be used to delete or retrieve the subscription
+ The subscriptionId value in the response may be used to delete or retrieve the subscription.
+
+ ## Example
+ To create a subscription, you can use the following example request:
+
+ POST /subscriptions
+ Content-Type: application/json
+ {
+ \"webhook\": {
+ \"notificationUrl\": \"https://example.com/notifications\",
+ \"notificationAuthToken\": \"my-auth-token\"
+ },
+ \"subscriptionExpireTime\": \"2024-03-13T12:55:23Z\",
+ \"subscriptionDetail\": {
+ \"type_sne\": \"my-event-type\"
+ }
+ }
+
+
+ ## Most frequent errors
+ The most frequent errors when creating a subscription include invalid arguments, unauthenticated requests, permission denied, and internal server errors.
+
+ # **Request list of subscriptions**
+ ## Summary of request body parameters
+ ## Summary of response body parameters
+ The request body is not used for this operation.
+
+ The response body includes an array of Subscription objects, each representing an event subscription.
+
+ ## Example
+ To retrieve a list of subscriptions, you can use the following example request:
+
+ GET /subscriptions
+
+
+ ## Most frequent errors
+ The most frequent errors when retrieving a list of subscriptions include invalid arguments, unauthenticated requests, and internal server errors.
+
+ # **Query a subscription by identifier**
+ ## Summary of request body parameters
+ The request body is not used for this operation.
+
+ ## Summary of response body parameters
+ The response body includes a Subscription object representing the specified event subscription.
+
+ # Example
+ To retrieve a specific subscription, you can use the following example request:
+
+ GET /subscriptions/{subscriptionId}
+
+
+ ## Most frequent errors
+ The most frequent errors when retrieving a specific subscription include invalid arguments, unauthenticated requests, and internal server errors.
+
+ # **Delete a subscription by identifier**
+ ## Summary of request body parameters
+ The request body is not used for this operation.
+
+ ## Summary of response body parameters
+ The response body is not used for this operation.
+
+ ## Example
+ To delete a specific subscription, you can use the following example request:
+
+ DELETE /subscriptions/{subscriptionId}
+
+
+ ## Most frequent errors
+ The most frequent errors when deleting a specific subscription include invalid arguments, unauthenticated requests, and internal server errors.
+
+
+ * **Authentication**:
+ Security access keys such as OAuth 2.0 client credentials used by client applications to invoke the Notification API.
+
+ # Further info and support
+
+ ## Frequently Asked Questions (FAQs)
+
+ 1. What is the purpose of the CAMARA Subscription, Notification & Event (SNE) Common API?
+
+
+ The CAMARA Subscription, Notification & Event (SNE) Common API provides a programmable interface for developers and other users to subscribe to events and receive notifications.
+
+
+ 2. What are the limitations of the CAMARA Subscription, Notification & Event (SNE) Common API?
+
+
+ Sorting and pagination of notifications are not supported.
+
+
+ 3. What is authentication in the context of the CAMARA Subscription, Notification & Event (SNE) Common API?
+
+ Authentication refers to security access keys such as OAuth 2.0 client credentials used by client applications to invoke the Notification API.
+
+
+ 4. How can I request an event subscription using the CAMARA Subscription, Notification & Event (SNE) Common API?
+
+ You can request an event subscription by using the POST operation on the `/subscriptions` endpoint and providing the necessary information in the request body.
+
+
+ 5. How can I retrieve a list of event subscriptions using the CAMARA Subscription, Notification & Event (SNE) Common API?
+
+ You can retrieve a list of event subscriptions by using the GET operation on the `/subscriptions` endpoint. The list can be filtered based on optional query parameters.
+
+
+ 6. How can I retrieve a specific event subscription using the CAMARA Subscription, Notification & Event (SNE) Common API?
+
+ You can retrieve a specific event subscription by using the GET operation on the `/subscriptions/{subscriptionId}` endpoint and providing the subscription ID in the path parameter.
+
+
+ 7. How can I delete a specific event subscription using the CAMARA Subscription, Notification & Event (SNE) Common API?
+
+ You can delete a specific event subscription by using the DELETE operation on the `/subscriptions/{subscriptionId}` endpoint and providing the subscription ID in the path parameter.
+
+
+ 8. How can I retrieve a list of supported event types using the CAMARA Subscription, Notification & Event (SNE) Common API?
+
+ You can retrieve a list of supported event types by using the GET operation on the `/supportedEventTypes` endpoint.
+
+
+ 9. What is the role of the webhook object in the CAMARA Subscription, Notification & Event (SNE) Common API?
+
+ The webhook object is provided in the API's POST request and contains details for the event channel, such as the notification URL and the notification authentication token.
+
+
+ 10. What is the subscription ID and how is it used in the CAMARA Subscription, Notification & Event (SNE) Common API?
+
+ The subscription ID is a unique identifier for an event subscription. It is provided by the API server and can be used to retrieve, update, or delete a specific event subscription.
+
+ termsOfService: http://swagger.io/terms/
+ contact:
+ email: project-email@sample.com
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.1.9-wip
+externalDocs:
+ description: Product documentation at Camara
+ url: https://github.com/camaraproject/
+security:
+ - oAuth2ClientCredentials: []
+servers:
+ - url: "{apiRoot}/{basePath}"
+ variables:
+ apiRoot:
+ default: http://localhost:9091
+ description: API root
+ basePath:
+ default: sne/v0
+ description: Base path for the CAMARA Subscription, Notification & Event (SNE) Common API
+paths:
+ /subscriptions:
+ post:
+ tags:
+ - Request event subscription
+ summary: "Request event subscription"
+ description: Operation to request a event subscription.
+ operationId: subscribeToEventNotifications
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ webhook:
+ $ref: "#/components/schemas/Webhook"
+ subscriptionExpireTime:
+ $ref: "#/components/schemas/SubscriptionExpireTime"
+ subscriptionDetail:
+ $ref: "#/components/schemas/SubscriptionDetail"
+ required:
+ - webhook
+ callbacks:
+ notifications:
+ "{$request.body#/webhook/notificationUrl}":
+ post:
+ summary: "A callback to recieve event notifications"
+ description: |
+ Important: this endpoint is to be implemented by the API consumer.
+ The API provider will call this endpoint whenever any subscription related event occurs.
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/camara-cloud-event-common-v1.0.yaml#/components/schemas/CloudEventBase"
+ responses:
+ "204":
+ description: Successful notification
+ "400":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/InvalidArgument"
+ "401":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Unauthenticated"
+ "403":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/PermissionDenied"
+ "500":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Internal"
+ "503":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Unavailable"
+ security:
+ - {}
+ - notificationsBearerAuth: [ "{$request.body#/webhook.notificationAuthToken}" ]
+ responses:
+ "201":
+ description: Subscription Created
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/Subscription"
+ links:
+ DeleteSubscriptionWithId:
+ operationId: deleteSubscription
+ parameters:
+ subscriptionId: '$response.body#/subscriptionId'
+ description: The subscriptionId value in the response may be used to delete the subscritpion prior to its expiry.
+ GetSubscriptionWithId:
+ operationId: getSubscriptionById
+ parameters:
+ subscriptionId: '$response.body#/subscriptionId'
+ description: The subscriptionId value in the response may be used to retrieve the subscritpion prior to its expiry.
+ "400":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/InvalidArgument"
+ "401":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Unauthenticated"
+ "403":
+ $ref: "#/components/responses/SubscriptionPeriodNotAllowed403"
+ "409":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Internal"
+ "500":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Conflict"
+ "503":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Unavailable"
+ security:
+ - oAuth2ClientCredentials: []
+ - threeLegged:
+ - "sne-subscription-create"
+ get:
+ tags:
+ - Retrieve all event subscriptions
+ summary: "Retrieve all event subscriptions"
+ description: |
+ Retrieve a list of event subscriptions filtered based on the optional query names.
+ eg. GET /subscriptions?type=org.camaraproject.capability.v1.bitmask-vector-changed&expiresAt.lt=2023-10-11
+ Could be an empty list.
+ operationId: getSubscriptions
+ parameters:
+ - name: startsAt
+ in: query
+ schema:
+ $ref: "#/components/schemas/StartsAt"
+ required: false
+ - name: expiresAt
+ in: query
+ schema:
+ $ref: "#/components/schemas/ExpiresAt"
+ required: false
+ - name: type_sne
+ in: query
+ schema:
+ $ref: "#/components/schemas/SubscriptionDetail/properties/type_sne"
+ required: false
+ responses:
+ "200":
+ description: Subscriptions Found
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: "#/components/schemas/Subscription"
+ "400":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/InvalidArgument"
+ "401":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Unauthenticated"
+ "403":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Conflict"
+ "500":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/PermissionDenied"
+ "503":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Unavailable"
+ security:
+ - oAuth2ClientCredentials: []
+ - threeLegged:
+ - "sne-subscription-get"
+ options:
+ tags:
+ - Get Event Subscriptions Features
+ operationId: getSubscriptionsFeatures
+ description: Discover supported features and methods for this endpoint
+ responses:
+ "200":
+ description: OK
+ headers:
+ Allow:
+ schema:
+ type: string
+ default: "POST,GET,OPTIONS"
+ security:
+ - oAuth2ClientCredentials: []
+ - threeLegged:
+ - "sne-subscription-get"
+ /subscriptions/{subscriptionId}:
+ get:
+ tags:
+ - Retrieve specific event subscription
+ summary: "Retrieve specific event subscription"
+ description: Retrieve the subscription by subscriptionId
+ operationId: getSubscriptionById
+ parameters:
+ - name: subscriptionId
+ in: path
+ schema:
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/camara-cloude-event-common-v1.0.yaml#/components/schemas/SubscriptionId"
+ description: subscription identifier
+ required: true
+ responses:
+ "200":
+ description: Subscription Found
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/Subscription"
+ "400":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/InvalidArgument"
+ "401":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Unauthenticated"
+ "403":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Conflict"
+ "404":
+ $ref: "#/components/responses/NotificationApiNotFound404"
+ "500":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/PermissionDenied"
+ "503":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Unavailable"
+ security:
+ - oAuth2ClientCredentials: []
+ - threeLegged:
+ - "sne-subscription-get"
+ options:
+ tags:
+ - Get Event Subscription Features
+ operationId: getSubscriptionFeatures
+ description: Discover supported features and methods for this endpoint
+ parameters:
+ - name: subscriptionId
+ in: path
+ schema:
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/camara-cloude-event-common-v1.0.yaml#/components/schemas/SubscriptionId"
+ description: subscription identifier
+ required: true
+ responses:
+ "200":
+ description: OK
+ headers:
+ Allow:
+ schema:
+ type: string
+ default: "GET,OPTIONS"
+ security:
+ - oAuth2ClientCredentials: []
+ - threeLegged:
+ - "sne-subscription-get"
+ delete:
+ tags:
+ - Delete specific event subscription
+ summary: "Delete specific event subscription"
+ description: Operation to delete an event subscription
+ operationId: deleteSubscription
+ parameters:
+ - name: subscriptionId
+ in: path
+ schema:
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/camara-cloude-event-common-v1.0.yaml#/components/schemas/SubscriptionId"
+ description: subscription identifier
+ required: true
+ responses:
+ "204":
+ description: Successful subscription deletion (no body returned)
+ "400":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/InvalidArgument"
+ "401":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Unauthenticated"
+ "403":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Conflict"
+ "404":
+ $ref: "#/components/responses/NotificationApiNotFound404"
+ "500":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/PermissionDenied"
+ "503":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Unavailable"
+ security:
+ - oAuth2ClientCredentials: []
+ - threeLegged:
+ - "sne-subscription-delete"
+
+ /supportedEventTypes:
+ get:
+ tags:
+ - Retrieve event types
+ summary: "Retrieve event types"
+ description: A list of supported Event Types
+ responses:
+ "200":
+ description: Event Types Supported
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ type: string
+ "400":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/InvalidArgument"
+ "401":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Unauthenticated"
+ "403":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Conflict"
+ "500":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/PermissionDenied"
+ "503":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Unavailable"
+ security:
+ - oAuth2ClientCredentials: []
+ - threeLegged:
+ - "sne-eventtype-read"
+ options:
+ tags:
+ - Get Event Types Features
+ operationId: getEventTypesFeatures
+ description: Discover supported features and methods for this endpoint
+ responses:
+ "200":
+ description: OK
+ headers:
+ Allow:
+ schema:
+ type: string
+ default: "GET,OPTIONS"
+ security:
+ - oAuth2ClientCredentials: []
+ - threeLegged:
+ - "sne-eventtype-read"
+
+components:
+ securitySchemes:
+ oAuth2ClientCredentials:
+ description: |
+ The Runtime Restrictions API makes use of the OAUTH 2.0 client credentials grant which is applicable for server to server use cases involving trusted partners or clients without any protected user data involved. In this method the API invoker client is registered as a confidential client with an authorization grant type of client_credentials
+ type: oauth2
+ flows:
+ clientCredentials:
+ tokenUrl: https://api.example.com/oauth/token
+ scopes: {}
+ notificationsBearerAuth:
+ type: http
+ scheme: bearer
+ bearerFormat: "{$request.body#/webhook/notificationAuthToken}"
+ threeLegged:
+ type: oauth2
+ description: This API uses OAuth 2 with the authorization code grant flow.
+ flows:
+ authorizationCode:
+ authorizationUrl: https://api.example.com/oauth2/authorize
+ tokenUrl: https://api.example.com/oauth/token
+ scopes:
+ sne-subscription-create: Create one subscription
+ sne-subscription-get: Retrieval of one or list of subscriptions
+ sne-subscription-delete: Delete one subscription
+ sne-eventtype-read: Retrieval of EventType supported
+
+ schemas:
+ Subscription:
+ description: Event subscription
+ type: object
+ properties:
+ webhook:
+ $ref: "#/components/schemas/Webhook"
+ subscriptionId:
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/camara-cloude-event-common-v1.0.yaml#/components/schemas/SubscriptionId"
+ subscriptionExpireTime:
+ $ref: "#/components/schemas/SubscriptionExpireTime"
+ startsAt:
+ $ref: "#/components/schemas/StartsAt"
+ expiresAt:
+ $ref: "#/components/schemas/ExpiresAt"
+ subscriptionDetail:
+ $ref: "#/components/schemas/SubscriptionDetail"
+ required:
+ - webhook
+ - subscriptionId
+
+ Webhook:
+ description: The object provided in an API's POST with detail for event channel.
+ type: object
+ properties:
+ notificationUrl:
+ description: https callback address where the notification must be POST-ed
+ type: string
+ format: url
+ example: "https://api-consumer.example.com/notification"
+ notificationAuthToken:
+ description: "OAuth2 token to be used by the callback API endpoint. It MUST be indicated within HTTP Authorization header e.g. Authorization: Bearer $notificationAuthToken"
+ type: string
+ minLength: 20
+ maxLength: 256
+ example: "c8974e592c2fa383d4a3960714"
+ required:
+ - notificationUrl
+
+ SubscriptionExpireTime:
+ description: Date when the event subscription should end. Provided by API requester. Server may reject the suscription if the period requested do not comply with Telco Operator policies (i.e. to avoid unlimited time subscriptions). In this case server returns exception 403 "SUBSCRIPTION_PERIOD_NOT_ALLOWED"
+ type: string
+ format: date-time
+
+ StartsAt:
+ description: Date when the event subscription will begin/began. This attribute must not be present in the POST request as it is provided by API server. It must be present in GET endpoints
+ type: string
+ format: date-time
+
+ ExpiresAt:
+ description: Date when the event subscription will expire. This attribute must not be present in the POST request as it is provided by API server.
+ type: string
+ format: date-time
+
+ SubscriptionDetail:
+ description: Object defined for each event subscription depending on the event - it could be for example the ueID targeted by the subscription
+ type: object
+ properties:
+ type_sne:
+ type: string
+ required:
+ - type_sne
+
+ responses:
+ SubscriptionPeriodNotAllowed403:
+ description: "Service does not allowed the provided subscription period"
+ content:
+ application/json:
+ schema:
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/schemas/ErrorInfo"
+ example:
+ status: 403
+ code: SUBSCRIPTION_PERIOD_NOT_ALLOWED
+ message: "The period requested does not comply with Telco Operator policies"
+
+ NotificationApiNotFound404:
+ description: Notification API not found
+ content:
+ application/json:
+ schema:
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/schemas/ErrorInfo"
+ example:
+ status: 404
+ code: NOT_FOUND
+ message: "No Notification API found"
diff --git a/APIBacklog/documentation/SupportingDocuments/others/capabilities/camara-runtime-restrictions-api-v0.1.6.yaml b/APIBacklog/documentation/SupportingDocuments/others/capabilities/camara-runtime-restrictions-api-v0.1.6.yaml
new file mode 100644
index 00000000..0ac4f7a0
--- /dev/null
+++ b/APIBacklog/documentation/SupportingDocuments/others/capabilities/camara-runtime-restrictions-api-v0.1.6.yaml
@@ -0,0 +1,898 @@
+openapi: 3.0.3
+info:
+ title: CAMARA Runtime Restrictions API
+ description: |
+ The CAMARA Runtime Restrictions API provides a programmable interface for developers and other users to discover API restrictions for
+ CAMARA projects.
+
+ # Introduction
+
+ This API allows users to discover restrictions to services, including operations and values. Runtime restrictions limit the use of
+ operations, parameters, or schema elements.
+
+ The goal of this API is to allow API consumers to identify differences between implementations of the same API which reflect
+ implementation decisions, capabilities, and operational practices.
+
+ ##Example Restriction Scenarios
+ - **Unsupported optional parameters:** The CAMARA Device object
+ requires one of four identifier types to be present. However, the API provide only supports two of them. If an API Consumer
+ does not provide the supported identifiers, they are sending invalid requests.
+ - **Minimum accuracy for DeviceLocation Area:** Due to legal or technical reasons, the minimum accuracy value in an API may be too small -
+ violating privacy or technical capability. In such cases, the API provider MUST convey the higher minimum accuracy value allowed.
+ - **Different authorization flows for API scopes:** Using restrictions, an API provider can declare which scopes require specific
+ authorization flow types.
+
+ ## Restriction Rules
+
+ - Valid Restrictions result in valid requests sent to the APIs they affect. For example, a restriction would be invalid if
+ it sets an integer property's maximum value to 4 when its schema sets its minimum at 5. APIs MUST never pass invalid restrictions.
+ Invalid restrictions MUST be ignored by the Client.
+
- Any schema instance may have metadata (deprecated, readOnly) or general (type, enum, const) restrictions applied to it.
+
- Restrictions apply to primitive types as follows:
+
+ - "numeric" instance validation keywords
+
- "strings" - validation keywords as defined by validation keywords
+
- "array" - validation keywords as defined by validation keywords
+
- "object" - restriction mechanisms are
+
+ - object instance validation keywords
+
- excludedProperties_rr - A list of optional properties that MUST NOT be present in the object
+
+
+
+
+ - Parameters may also be restricted. General schema restrictions, i.e., Any Instance, apply. Parameters MAY further be restricted as follows:
+
+ - Deprecate use of a parameter. This can only be done if the original schema does not have 'required: true' for this
+ parameter specification.
+
- Mandate use of an optional parameter. This can only be done if the original schema does not have 'deprecated: true'
+ for this parameter specification.
+
- Allow empty values. This can only be TRUE if the schema did not explicitly specify its value as false.
+
+
+ - Restrictions may apply to subschemas that are applied with logic keywords "anyOf" or "oneOf". When restricted, the specific
+ subschema is treated as if it were added to an adjacent "not" subschema, i.e., subschemas in the same location in the instance as
+ the parent schema. For example, given
+
+ "oneOf": [ { "$ref": "#/definitions/structa" }, {"$ref": "#/definitions/structb" } ]
+
+ A Restriction of
{ "subschemaScope" : "oneOf", "subschemaRef": "#/definitions/structb" } would restrict the nodes to only values of structa.
+ - Setting a referenced item to 'readonly', effectively noting that its value will be ignored by the server.
+
- If the API producer doesn't implement all optional API operations defined, such operations can be restricted by declaring the operation
+
+ - 'deprecated', as long as the original schema did not explicitly specify its value as false,
+
- 'not available', for temporary unavailability
+
- or 'not implemented', if the operation hasn't been implemented.
+
+
+
+
+
+ All runtime restrictions end with the suffix '_rr'.
+
+ ## References
+
+ The target of restrictions is comprised of 5 parts
+
+ - An optional operationRefs list that defines referenced operations. List entries follow the operationRef syntax.
+ - An optional operationIds list which describes a list of operation identifiers.
+ - An optional list of parameter names. When this parameter is present, the appliesToRequestBody parameter MUST also be present.
+ - appliesToRequestBody is a boolean that indicates that restrictions apply to request bodies as well as the specified list of parameters.
+ - A list of subjects which the restrictions apply to. List entries are operation parameter names OR follow the $ref syntax.
+
+
+ Restrictions are applied upon 3 parts of any request:
+
+ - operations - referenced in OperationReferences as lists of operationRefs and operationIds
+ - path parameters - referenced in ParameterReferences parameters list
+ - operation request body - referenced in ParameterReferences parameters list when its appliesToRequestBody property value is
true
+
+
+ When ParameterReferences does not contain OperationReferences, the ParameterReferences applies across any operations.
+
+ Restrictions use a Context which is an array of ParameterReferences, OperationReferences and PropertyTests.
+ For any request, if all values in the Context equate to true then restrictions are applied to the subjects of the Restriction.
+
+ ## LIMITATIONS/OPEN ITEMS
+
+ - Due to use of openapi 3.0.3, const_rr and default_rr are limited to string types. Use of openapi 3.1 is required to use the 'any' type, i.e., '{}'.
+ - Add more examples.
+
+ - Address type discriminator to resolve the Civic address issue by type for TM Forum
+ - JSON-LD context example test for GS1 resolution of location vs postal address
+
+
+
+
+ # Usage
+ API Consumers first use a GET operation to acquire **Runtime Restrictions** by name. Additionally, API Consumers
+ may acquire the URL of the **Runtime Restrictions Notification Server** to subscribe to subsequent
+ changes in Runtime Restrictions. Two event types are supported
+
+ - RuntimeRestrictionRemovedEvent includes the Runtime Restriction that has been removed.
+
- RuntimeRestrictionChangedEvent includes the changed event. In this event the name of RuntimeRestriction indicates
+ the target RuntimeRestriction but its version has changed. If a cacheId is included, it may be used to indicate the RuntimeRestricion
+ that will be updated. Any new references to the cacheId will use the event's RuntimeRestriction as its target.
+
+
+
+ # Relevant terms and definitions
+
+ * **API restrictions**:
+ A set of measures put in place to help ensure the stability and performance of an API system. It works by setting limits on how many
+ requests can be made within a certain period of time and what actions can be taken.
+
+ * **Authentication**:
+ Security access keys such as OAuth 2.0 client credentials used by client applications to invoke the Runtime Restrictions API.
+
+ * **Runtime restrictions**:
+ Limits that are applied during the execution of a program or system
+
+ # Further info and support
+
+ ## Frequently Asked Questions (FAQs)
+ 1. What is the purpose of the Runtime Restrictions API? The Runtime Restrictions API provides a programmable interface for developers and other users
+ to discover API restrictions for projects.
+
+ 2. What are some examples of restriction scenarios that the Runtime Restrictions API can handle? Some examples of restriction scenarios that the Runtime Restrictions API
+ can handle include unsupported optional parameters, minimum accuracy for DeviceLocation Area, and different authorization flows for API scopes.
+
+ 3. What are the rules for valid restrictions in the Runtime Restrictions API? Valid restrictions result in valid requests sent to the APIs they affect.
+ For example, a restriction would be invalid if it sets an integer property's maximum value to 4 when its schema sets its minimum at 5. APIs must never pass invalid restrictions.
+ Invalid restrictions must be ignored by the client.
+
+ 4. How can I acquire runtime restrictions using the Runtime Restrictions API? API Consumers first use a GET operation to acquire runtime restrictions by name.
+ Additionally, API Consumers may acquire the URL of the runtime restrictions notification server to subscribe to subsequent changes in runtime restrictions.
+
+ 5. What are the event types supported by the Runtime Restrictions API? Two event types are supported: RuntimeRestrictionRemovedEvent, which includes the runtime restriction
+ that has been removed, and RuntimeRestrictionChangedEvent, which includes the changed event.
+
+ 6. What are API restrictions? API restrictions are a set of measures put in place to help ensure the stability and performance of an API system. It works by setting limits on
+ how many requests can be made within a certain period of time and what actions can be taken.
+
+ 7. What is authentication in the context of the Runtime Restrictions API? Authentication refers to security access keys such as OAuth 2.0 client credentials used by client applications
+ to invoke the Runtime Restrictions API.
+
+ 8. What are runtime restrictions? Runtime restrictions are limits that are applied during the execution of a program or system.
+
+ 9. How can I discover the supported endpoing (HTTP) features and methods for the CAMARA Runtime Restrictions API? You can discover the supported features and methods for the CAMARA Runtime Restrictions API
+ by using the OPTIONS operation on the relevant endpoint.
+ termsOfService: http://swagger.io/terms/
+ contact:
+ email: project-email@sample.com
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.1.5-wip
+externalDocs:
+ description: Product documentation at Camara
+ url: https://github.com/camaraproject/
+security:
+ - oAuth2ClientCredentials: []
+servers:
+ - url: "{apiRoot}/{basePath}"
+ variables:
+ apiRoot:
+ default: http://localhost:9091
+ description: API root
+ basePath:
+ default: rr/v0
+ description: Base path for the CAMARA Runtime Restrictions (RR) API
+paths:
+ /rr-notification-server:
+ get:
+ tags:
+ - Notification Server URL
+ summary: |
+ Returns the notification server URL for the capabilities API provider..
+ description: |
+ Returns the notification server URL for the capabilities API provider. This will be returned with HTTP Status Code 301
+ (Moved Permanently). Code 301 is used instead of 302 (Temporary) to ensure the Client does not need to repeatedly poll
+ this path. The Notificxation's URL is returned as part of the Location Header.
+ operationId: getRRNotificationServerURL
+ responses:
+ "301":
+ description: Contains information about the notification server location
+ headers:
+ Location:
+ schema:
+ type: string
+ example: "https://api-provider.example.com/subscriptions"
+ "401":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Unauthenticated"
+ "403":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Conflict"
+ "404":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/NotFound"
+ "500":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/PermissionDenied"
+ "503":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Unavailable"
+ security:
+ - oAuth2ClientCredentials: []
+ - threeLegged:
+ - "rr-notification-server-read"
+ options:
+ tags:
+ - Get Notification Server URL Features
+ operationId: getRRNotificatServerFeatures
+ description: Discover supported features and methods for this endpoint
+ responses:
+ "200":
+ description: OK
+ headers:
+ Allow:
+ schema:
+ type: string
+ default: "GET,OPTIONS"
+ security:
+ - oAuth2ClientCredentials: []
+ - threeLegged:
+ - "rr-notification-server-read"
+
+ /runtimerestrictions/{identifier}:
+ get:
+ tags:
+ - Query runtime restrictions for a specific service API or group of Restrictions
+ summary: Get runtime restrictions for specified service API
+ description: |
+ Returns the runtime restrictions of for a specific service API or group of Restrictions on the gateway.
+ operationId: getRuntimeRestrictions
+ parameters:
+ - name: identifier
+ in: path
+ description: Identifier of the set of restrictions to retrieve. It could be an API name or some other string.
+ schema:
+ type: string
+ minLength: 1
+ required: true
+ responses:
+ "200":
+ description: Contains information about service API runtime restrictions
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: "#/components/schemas/Restrictions"
+ examples:
+ AcceptedDeviceIdentifiers:
+ description: ipv4Address and networkAccessIdentifier are not supported within https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/qod-api.yaml
+ value:
+ {
+ "cacheId": "rr1",
+ "identifiers": [
+ "AcceptedDeviceIdentifiers"
+ ],
+ "version": "0.0.1",
+ "subjects": [
+ "https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/qod-api.yaml#/paths/~1sessions/post/requestBody/content/application~1json/schema/CreateSession/properties/device/"
+ ],
+ "restrictions": [
+ {
+ "excludedProperties_rr": [
+ "https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/qod-api.yaml#/components/schemas/Device/ipv4Address",
+ "https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/qod-api.yaml#/components/schemas/Device/networkAccessIdentifier"
+ ],
+ "rrType": "ObjectInstanceRestriction"
+ }
+ ]
+ }
+ OfferedQoSProfiles:
+ description: return Offered QoSProfiles within https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/qod-api.yaml
+ value:
+ {
+ "cacheId": "rr2",
+ "identifiers": [
+ "OfferedQoSProfiles"
+ ],
+ "version": "0.0.1",
+ "operationIds": [
+ "https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/qod-api.yaml#/paths/~1/qos-profiles/get"
+ ],
+ "subjects": [
+ "https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/qod-api.yaml#/components/schemas/QosProfileStatusEnum"
+ ],
+ "restrictions": [
+ {
+ "enum_rr": [
+ "https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/qod-api.yaml#/components/schemas/QosProfileStatusEnum/enum/2",
+ "https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/qod-api.yaml#/components/schemas/QosProfileStatusEnum/enum/3"
+ ],
+ "rrType": "AnyInstanceRestriction"
+ }
+ ]
+ }
+ CreateSessionOperationNotSupported:
+ description: declare new CreateSession operation is no longer supported within https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/qod-api.yaml
+ value:
+ {
+ "cacheId": "rr3",
+ "identifiers": [
+ "CreateSessionOperationNotSupported"
+ ],
+ "version": "0.0.1",
+ "subjects": [
+ "https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/qod-api.yaml#/paths/~1sessions/post"
+ ],
+ "restrictions": [
+ {
+ "deprecated_rr": true,
+ "rrType": "OperationRestriction"
+ }
+ ]
+ }
+ NotificationSubscriptionTimeFilterNotSupported:
+ description: declare filtering on time related paramaters of notification getSubscriptions operation is supported yet within https://github.com/camaraproject/Commonalities/tree/main/artifacts/camara-notification-api.yaml
+ value:
+ {
+ "cacheId": "rr4",
+ "identifiers": [
+ "NotificationSubscriptionTimeFilterNotSupported"
+ ],
+ "version": "0.0.1",
+ "subjects": [
+ "https://github.com/camaraproject/Commonalities/tree/main/artifacts/camara-notification-api.yaml#/paths/~1subscriptions/get/parameters"
+ ],
+ "restrictions": [
+ {
+ "excludedProperties_rr": [
+ "StartsAt",
+ "ExpiresAt"
+ ],
+ "rrType": "ObjectInstanceRestriction"
+ }
+ ]
+ }
+ LocationRadiusRange:
+ description: declare new range of location radius supported within https://github.com/camaraproject/DeviceLocation/blob/main/code/API_definitions/location-verification.yaml
+ value:
+ {
+ "cacheId": "rr5",
+ "identifiers": [
+ "LocationRadiusRange"
+ ],
+ "version": "0.0.1",
+ "subjects": [
+ "https://github.com/camaraproject/DeviceLocation/blob/main/code/API_definitions/location-verification.yaml#/components/schemas/Circle/radius"
+ ],
+ "restrictions": [
+ {
+ "minimum_rr": 3000,
+ "maximum_rr": 30000,
+ "rrType": "NumericInstanceRestriction"
+ }
+ ]
+ }
+ ServingAreaBellevueWARadius:
+ description: declare restricted radius of the serving area supported within https://github.com/camaraproject/DeviceLocation/blob/main/code/API_definitions/location-retrieval.yaml
+ value:
+ {
+ "cacheId": "rr6",
+ "identifiers": [
+ "ServingAreaBellevueWARadius"
+ ],
+ "subjects": [
+ "https://github.com/camaraproject/DeviceLocation/blob/main/code/API_definitions/location-retrieval.yaml#/components/schemas/Circle/radius"
+ ],
+ "restrictions": [
+ {
+ "minimum_rr": 1000000,
+ "maximum_rr": 1000000,
+ "rrType": "NumericInstanceRestriction"
+ }
+ ]
+ }
+ ServingAreaBellevueWALatitude:
+ description: declare restricted latitude of the serving area supported within https://github.com/camaraproject/DeviceLocation/blob/main/code/API_definitions/location-retrieval.yaml
+ value:
+ {
+ "cacheId": "rr7",
+ "identifiers": [
+ "ServingAreaBellevueWALatitude"
+ ],
+ "subjects": [
+ "https://github.com/camaraproject/DeviceLocation/blob/main/code/API_definitions/location-retrieval.yaml#/components/schemas/Latitude"
+ ],
+ "restrictions": [
+ {
+ "minimum_rr": 47.610377,
+ "maximum_rr": 47.610377,
+ "rrType": "NumericInstanceRestriction"
+ }
+ ]
+ }
+ ServingAreaBellevueWALongitude:
+ description: declare restricted longitude of the serving area supported within https://github.com/camaraproject/DeviceLocation/blob/main/code/API_definitions/location-retrieval.yaml
+ value:
+ {
+ "cacheId": "rr8",
+ "identifiers": [
+ "ServingAreaBellevueWALongitude"
+ ],
+ "subjects": [
+ "https://github.com/camaraproject/DeviceLocation/blob/main/code/API_definitions/location-retrieval.yaml#/components/schemas/Longitude"
+ ],
+ "restrictions": [
+ {
+ "minimum_rr": -122.2006786,
+ "maximum_rr": -122.2006786,
+ "rrType": "NumericInstanceRestriction"
+ }
+ ]
+ }
+ SupportedScopesPerAuthFlow1:
+ description: Requiring the all scopes to be populated in each authflow defined in the components/securitySchemes following will reduce the applicable scopes to each auth flow type
+ value:
+ {
+ "cacheId": "rr9",
+ "identifiers": [
+ "SupportedScopesPerAuthFlow1"
+ ],
+ "subjects": [
+ "https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/qod-api.yaml#/components/securitySchemes/threeLegged/flows/authorizationCode/scopes"
+ ],
+ "restrictions": [
+ {
+ "enum_rr": [
+ "https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/qod-api.yaml#/components/securitySchemes/threeLegged/flows/authorizationCode/scopes/2",
+ "https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/qod-api.yaml#/components/securitySchemes/threeLegged/flows/authorizationCode/scopes/3"
+ ],
+ "rrType": "AnyInstanceRestriction"
+ }
+ ]
+ }
+ SupportedScopesPerAuthFlow2:
+ description: Requiring the all scopes to be populated in each authflow defined in the components/securitySchemes following will reduce the applicable scopes to each auth flow type
+ value:
+ {
+ "cacheId": "rr10",
+ "identifiers": [
+ "SupportedScopesPerAuthFlow2"
+ ],
+ "subjects": [
+ "https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/qod-api.yaml#/components/securitySchemes/threeLegged/flows/authorizationCode/scopes"
+ ],
+ "restrictions": [
+ {
+ "enum_rr": [
+ "https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/qod-api.yaml#/components/securitySchemes/oAuth2ClientCredentials/flows/clientCredentials/scopes/1",
+ "https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/qod-api.yaml#/components/securitySchemes/oAuth2ClientCredentials/flows/clientCredentials/scopes/4"
+ ],
+ "rrType": "AnyInstanceRestriction"
+ }
+ ]
+ }
+ "401":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Unauthenticated"
+ "403":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Conflict"
+ "404":
+ $ref: "#/components/responses/RestrictionsApiNotFound404"
+ "500":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/PermissionDenied"
+ "501":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/NotImplemented"
+ "503":
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/responses/Unavailable"
+ security:
+ - oAuth2ClientCredentials: []
+ - threeLegged:
+ - "rr-read"
+ options:
+ tags:
+ - Get Runtime Restrctions Features
+ operationId: getRuntimeRestrictionsFeatures
+ description: Discover supported features and methods for this endpoint
+ parameters:
+ - name: identifier
+ in: path
+ description: Identifier of the set of restrictions to retrieve. It could be an API name or some other string.
+ schema:
+ type: string
+ minLength: 1
+ required: true
+ responses:
+ "200":
+ description: OK
+ headers:
+ Allow:
+ schema:
+ type: string
+ default: "GET,OPTIONS"
+ security:
+ - oAuth2ClientCredentials: []
+ - threeLegged:
+ - "rr-read"
+
+components:
+ securitySchemes:
+ oAuth2ClientCredentials:
+ description: |
+ The Runtime Restrictions API makes use of the OAUTH 2.0 client credentials grant which is applicable for server to server use cases involving trusted partners or clients without any protected user data involved. In this method the API invoker client is registered as a confidential client with an authorization grant type of client_credentials
+ type: oauth2
+ flows:
+ clientCredentials:
+ tokenUrl: https://api.example.com/oauth/token
+ scopes: {}
+ threeLegged:
+ type: oauth2
+ description: This API uses OAuth 2 with the authorization code grant flow.
+ flows:
+ authorizationCode:
+ authorizationUrl: https://api.example.com/oauth2/authorize
+ tokenUrl: https://api.example.com/oauth/token
+ scopes:
+ rr-notification-server-read: Retrieval of Runtime Restrictions API provider notification server
+ rr-read: Retrieval of Runtime Restrictions
+
+ schemas:
+ BaseRestriction:
+ description: base (parent) of all types of restrictions
+ type: object
+ required:
+ - rrType
+ properties:
+ rrType:
+ description: Object type used as a discriminator.
+ type: string
+
+ AnyInstanceMetaRestriction:
+ description: Based upon the JSON Schema A Vocabulary for Basic Meta-Data Annotations. Note that 'writeOnly was not added as a runtime restriction as it applies to only input (request restrictions).'
+ allOf:
+ - $ref: '#/components/schemas/BaseRestriction'
+ - type: object
+ properties:
+ deprecated_rr:
+ description: See deprecated.
+ type: boolean
+ readOnly_rr:
+ description: See readOnly.
+ type: boolean
+ writeOnly_rr:
+ description: See writeOnly. For security reasons, this can only be used when the writeonly property was not explicitly set to 'true' in the schema specification.
+ type: boolean
+ default_rr:
+ description: See default.
+ type: string
+ minProperties: 1
+
+ AnyInstanceRestriction:
+ description: Based upon the JSON Schema validation keywords for Any instances
+ allOf:
+ - $ref: '#/components/schemas/BaseRestriction'
+ - type: object
+ properties:
+ type_rr:
+ description: See type. Note this can only be applied if the type property was not specified for the scope within the schema specification.
+ type: string
+ enum: [ "null", "boolean", "object", "array", "number", "string", "integer" ]
+ enum_rr:
+ description: See enum Note this can only be applied if the enum property was not specified for the scope within the schema specification or it specifies a subset of the enum list in the schema specification.
+ type: array
+ items: {}
+ const_rr:
+ description: See const Note this can only be applied if the const property was not specified for the scope within the schema specification.
+ type: string
+ minProperties: 1
+
+ NumericInstanceRestriction:
+ description: Based upon the JSON Schema validation keywords for Numeric Instances
+ allOf:
+ - $ref: '#/components/schemas/BaseRestriction'
+ - type: object
+ properties:
+ multipleOf_rr:
+ description: See multipleOf
+ type: integer
+ minimum: 1
+ maximum_rr:
+ description: See maximum
+ type: integer
+ minimum_rr:
+ description: See minimum
+ type: integer
+ exclusiveMaximum_rr:
+ description: See exclusiveMaximum
+ type: integer
+ exclusiveMinimum_rr:
+ description: See exclusiveMinimum
+ type: integer
+ minProperties: 1
+
+ StringInstanceRestriction:
+ description: Based upon the JSON Schema validation keywords for Strings
+ allOf:
+ - $ref: '#/components/schemas/BaseRestriction'
+ - type: object
+ properties:
+ maxLength_rr:
+ description: See maxLength
+ type: integer
+ minimum: 0
+ minLength_rr:
+ description: See minLength
+ type: integer
+ minimum: 0
+ pattern_rr:
+ description: See pattern
+ type: string
+ minProperties: 1
+
+ ArrayInstanceRestriction:
+ description: Based upon the JSON Schema validation keywords for Array Instances
+ allOf:
+ - $ref: '#/components/schemas/BaseRestriction'
+ - type: object
+ properties:
+ maxItems_rr:
+ description: See maxItems
+ type: integer
+ minimum: 0
+ minItems_rr:
+ description: See minItems
+ type: integer
+ minimum: 0
+ uniqueItems_rr:
+ description: See uniqueItems
+ Note - this value can only be FALSE if the original schema did not define the value as TRUE.
+ type: boolean
+ maxContains_rr:
+ description: See maxContains
+ type: integer
+ minimum: 0
+ minContains_rr:
+ description: See minContains
+ type: integer
+ minimum: 0
+ minProperties: 1
+
+ ObjectInstanceRestriction:
+ description: Based upon the JSON Schema validation keywords for Object Instances
+ allOf:
+ - $ref: '#/components/schemas/BaseRestriction'
+ - type: object
+ properties:
+ maxProperties_rr:
+ description: See maxProperties
+ type: integer
+ minimum: 0
+ minProperties_rr:
+ description: See minProperties
+ type: integer
+ minimum: 0
+ required_rr:
+ description: See required
+ type: array
+ items:
+ type: string
+ minItems: 1
+ dependentRequired_rr:
+ description: See dependentRequired
+ type: array
+ items:
+ type: string
+ minItems: 1
+ excludedProperties_rr:
+ description: A list of properties that MUST be excluded.
+ type: array
+ items:
+ type: string
+ minItems: 1
+ minProperties: 1
+
+ ParameterRestriction:
+ description: |
+ Based upon the Swagger Parameter Object, it
+ provides the following types of restrictions:
+
+ - Mandate use of an optional parameter
+ - Allow empty values.
+
+ The conditions under which these restrictions apply are specified in the property defintions.
+ allOf:
+ - $ref: '#/components/schemas/BaseRestriction'
+ - type: object
+ properties:
+ allowEmptyValue_rr:
+ description: "Allows empty values. This can only be true if the schema did not explicitly specify its value as false."
+ type: boolean
+ mandatory_rr:
+ description: |
+ Based upon the Swagger Parameter Object, it mandates use of an optional parameter. This can only be done if
+
+ - The original schema does not have
deprecated: true for this parameter.
+ - The original schema does not explicitly set
mandatory to a value that is opposite of the value of this parameter.
+
+ type: boolean
+ minProperties: 1
+
+ OperationRestriction:
+ description: |
+ Based upon the Swagger Operation Object, it
+ provides the following types of restrictions:
+
+ - notImplemented
+ - notAvailable
+
+ allOf:
+ - $ref: '#/components/schemas/BaseRestriction'
+ - type: object
+ properties:
+ notAvailable:
+ description: |
+ Indicates if the operation is not available. If true, invocation of the referenced operations will result in a HTTP Server reponse of 501 - Not Implemented
+ type: boolean
+ notImplemented:
+ description: |
+ Indicates if the operation is not implemented. If true, invocation of the referenced operations will result in a HTTP Server reponse of 503 - Not Available
+ type: boolean
+ minProperties: 1
+
+ OperationReferences:
+ description: A set of operations described by either OperationRefs or operataionIds.
+ type: object
+ properties:
+ operationRefs:
+ description: A list of referenced operations. Entries follow the operationRef syntax.
+ type: array
+ items:
+ type: string
+ minItems: 1
+ operationIds:
+ description: A list referenced operations. Entries follo the operation identifiers syntax.
+ type: array
+ items:
+ type: string
+ minItems: 1
+
+ ParameterReferences:
+ description: A list of parameters runtime restrictions apply to. It contains an indicator noting if the accompanied runtime restrictions
+ apply not only to operation parameters but also parameters of the same name in request bodies.
+ allOf:
+ - $ref: "#/components/schemas/OperationReferences"
+ - type: object
+ properties:
+ parameters:
+ description: list of parameter names
+ type: array
+ items:
+ type: string
+ minItems: 1
+ appliesToRequestBody:
+ description: Indicates that restrictions apply to requestBody as well as the specified list of parameters.
+ type: boolean
+ required: [ "parameters", "appliesToRequestBody" ]
+
+ PropertyTest:
+ description: A boolean test on a property. It MUST evaluate to true in order to have associated runtime restrictions applied.
+ type: object
+ properties:
+ name:
+ description: Property Name. If it includes a relative path, it applies to the request body. Otherwise, it applies to a parameter.
+ type: string
+ value:
+ description: Value of the object. As of this writing, it is limited to a string.
+ type: string
+ test:
+ description: Type of test to apply. It MUST be applicable to the property type or it can be ingored by the client.
+
+ - eq - equals
+ - ne - not equal
+ - present - The property is present in the structure.
+ - presentNotEmpty - The property is present in the structure and non-emptry.
+ - absent - The property is not present.
+ - lte - less than or equal to
+ - lt - less than
+ - gte - greater than or equal to
+ - gt - greater than
+
+ type: string
+ enum: [ "eq", "ne", "present", "presentNotEmpty", "absent", "lte", "le", "lt", gte", "gt" ]
+
+ Restrictions:
+ description: "The restrictions and scope (operations, parameters, operation request bodies or entire schema) a set of restrictions applies to."
+ type: object
+ properties:
+ cacheId:
+ description: A cache identifier. This is a unique key for management of updates between the API provider and consumers. When this value is not provided, cache management, if provided, occurs via implementation specific means.
+ type: string
+ minLength: 1
+ identifiers:
+ description: An array of identifiers this set of restrictions is known by. Using any one of them via this API will result in retrieval of this instance of the restrictions.
+ type: array
+ items:
+ type: string
+ minItems: 1
+ version:
+ description: Restrictions version.
+ type: string
+ context:
+ description: An array of items that equate to boolean values. If all items are true then the restrictions are enforced to the subject(s). For example, if an array element has an opeationRef/operationId and a corresponding parameter in a paraemters list, an object contains a specific value, etc. Note that some array elements apply to operations to be invoked (or their parameters) while others apply to subjects. If this value is empty, the context is satisfied.
+ type: array
+ items:
+ oneOf:
+ - $ref: "#/components/schemas/OperationReferences"
+ - $ref: "#/components/schemas/ParameterReferences"
+ - $ref: "#/components/schemas/PropertyTest"
+ subjects:
+ description: A list of subjects which the restrictions apply to. List entries follow the $ref syntax.
+ type: array
+ items:
+ type: string
+ minItems: 1
+ restrictions:
+ description: "A list of restrictions that limit what can be passed to an API. When applied, it MUST result in a valid request per the orginal schema specification."
+ type: array
+ minItems: 1
+ items:
+ oneOf: [
+ { $ref: "#/components/schemas/AnyInstanceMetaRestriction" },
+ { $ref: "#/components/schemas/AnyInstanceRestriction" } ,
+ { $ref: "#/components/schemas/NumericInstanceRestriction" } ,
+ { $ref: "#/components/schemas/StringInstanceRestriction" },
+ { $ref: "#/components/schemas/ArrayInstanceRestriction" },
+ { $ref: "#/components/schemas/ObjectInstanceRestriction" },
+ { $ref: "#/components/schemas/ParameterRestriction" },
+ { $ref: "#/components/schemas/OperationRestriction" }
+ ]
+ discriminator:
+ propertyName: rrType
+ required: [ "identifiers", "subjects", "restrictions" ]
+
+ RuntimeRestrictionRemovedEvent:
+ description: RuntimeRestrictions Removed cloud event.
+ allOf:
+ - $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/camara-cloud-event-common-v1.0.yaml#/components/CloudEventBase"
+ - type: object
+ properties:
+ data:
+ type: object
+ description: 'event details payload described in each CAMARA API and referenced by its "type"'
+ properties:
+ subscriptionId:
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/camara-cloud-event-common-v1.0.yaml#/components/SubscriptionId"
+ eventDetail:
+ $ref: '#/components/schemas/Restrictions'
+ required:
+ - eventDetail
+
+ RuntimeRestrictionChangedEvent:
+ description: RuntimeRestrictions Changed cloud event.
+ allOf:
+ - $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/camara-cloud-event-common-v1.0.yaml#/components/CloudEventBase"
+ - type: object
+ properties:
+ data:
+ type: object
+ description: 'event details payload described in each CAMARA API and referenced by its "type"'
+ properties:
+ subscriptionId:
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/camara-cloud-event-common-v1.0.yaml#/components/SubscriptionId"
+ eventDetail:
+ $ref: '#/components/schemas/Restrictions'
+ required:
+ - eventDetail
+
+ RuntimeRestrictionEvents:
+ description: Runtime Restriction Events.
+ oneOf:
+ - $ref: "#/components/schemas/RuntimeRestrictionChangedEvent"
+ - $ref: "#/components/schemas/RuntimeRestrictionRemovedEvent"
+ discriminator:
+ propertyName: type
+ mapping:
+ "org.camara.rr.0.1.5.RuntimeRestrictionChanged": "#/components/schemas/RuntimeRestrictionChangedEvent"
+ "org.camara.rr.0.1.5.RuntimeRestrictionRemoved": "#/components/schemas/RuntimeRestrictionRemovedEvent"
+
+ responses:
+ RestrictionsApiNotFound404:
+ description: Runtime Restriction API not found
+ content:
+ application/json:
+ schema:
+ $ref: "https://raw.githubusercontent.com/camaraproject/Commonalities/main/artifacts/CAMARA_common.yaml#/components/schemas/ErrorInfo"
+ example:
+ status: 404
+ code: NOT_FOUND
+ message: "No Runtime Restriction API found"