openapi: 3.2.0 info: title: Network as Code Device Roaming Status Subscriptions v0.8 API version: 1.0.0 description: Nokia's Network as Code API for programmable networks. x-category: Other x-long-description: Nokia's Network as Code API for programmable networks x-website: '' x-public: true x-thumbnail: https://rapidapi-prod-prodeu-apis.s3.eu-central-1.amazonaws.com/87fa562b-c40b-4a8f-9847-108b8973ce6f.png x-version-lifecycle: active x-badges: [] termsOfService: https://developer.networkascode.nokia.io/legal/terms-of-service x-collections: [] servers: - url: https://network-as-code.p-eu.rapidapi.com security: - ApiKeyAuth: [] tags: - name: Device Roaming Status Subscriptions v0.8 paths: /device-status/device-roaming-status-subscriptions/v0.8/subscriptions/{subscriptionId}: get: tags: - Device Roaming Status Subscriptions v0.8 summary: Retrieve a roaming status event subscription for a device parameters: - name: subscriptionId in: path required: true description: Subscription identifier that was obtained from the create event subscription operation schema: type: string description: The unique identifier of the subscription in the scope of the subscription manager. When this information is contained within an event notification, this concept SHALL be referred as subscriptionId as per Commonalities Event Notification Model. default: qs15-h556-rt89-1298 - name: x-correlator in: header required: false description: Correlation id for the different services schema: {} - $ref: '#/components/parameters/x-rapidapi-host' operationId: retrieveDeviceRoamingStatusSubscription-DS-ROS-V080 description: retrieve device roaming status subscription information for a given subscription. responses: '200': content: application/json: examples: Active Subscription: value: id: 550e8400-e29b-41d4-a716-446655440000 sink: https://endpoint.example.com/sink protocol: HTTP types: - org.camaraproject.device-roaming-status-subscriptions.v0.roaming-on config: subscriptionDetail: {} subscriptionExpireTime: '2024-07-17T13:18:23.682Z' subscriptionMaxEvents: 5 initialEvent: true startsAt: '2024-07-03T21:12:02.871Z' expiresAt: '2024-07-03T21:12:02.871Z' status: ACTIVE Active Subscription With Device Disambiguation: value: id: 550e8400-e29b-41d4-a716-446655440000 sink: https://endpoint.example.com/sink protocol: HTTP types: - org.camaraproject.device-roaming-status-subscriptions.v0.roaming-on config: subscriptionDetail: device: phoneNumber: '+99999991000' subscriptionExpireTime: '2024-07-17T13:18:23.682Z' subscriptionMaxEvents: 5 initialEvent: true startsAt: '2024-07-03T21:12:02.871Z' expiresAt: '2024-07-03T21:12:02.871Z' status: ACTIVE Subscription Activation Requested: value: id: 550e8400-e29b-41d4-a716-446655440000 sink: https://endpoint.example.com/sink protocol: HTTP types: - org.camaraproject.device-roaming-status-subscriptions.v0.roaming-on config: subscriptionDetail: {} subscriptionExpireTime: '2024-07-17T13:18:23.682Z' subscriptionMaxEvents: 5 initialEvent: true startsAt: '2024-07-03T21:12:02.871Z' expiresAt: '2024-07-03T21:12:02.871Z' status: ACTIVATION_REQUESTED Subscription Deleted: value: id: 550e8400-e29b-41d4-a716-446655440000 sink: https://endpoint.example.com/sink protocol: HTTP types: - org.camaraproject.device-roaming-status-subscriptions.v0.roaming-on config: subscriptionDetail: {} subscriptionExpireTime: '2024-07-17T13:18:23.682Z' subscriptionMaxEvents: 5 initialEvent: true startsAt: '2024-07-03T21:12:02.871Z' expiresAt: '2024-07-03T21:12:02.871Z' status: DELETED schema: description: Represents a event-type subscription. type: object required: - sink - protocol - config - types - id properties: protocol: type: string enum: - HTTP - MQTT3 - MQTT5 - AMQP - NATS - KAFKA description: Identifier of a delivery protocol. Only HTTP is allowed for now sink: type: string format: uri pattern: ^https:\/\/.+$ description: The address to which events shall be delivered using the selected protocol. types: description: "Camara Event types eligible to be delivered by this subscription.\nNote: for the Commonalities meta-release v0.4 we enforce to have only event type per subscription then for following meta-release use of array MUST be decided\n\n\n\n\n\n at API project level.\n" type: array minItems: 1 maxItems: 1 items: type: string description: 'roaming-status - Event triggered when the device switch from roaming ON to roaming OFF and conversely roaming-on - Event triggered when the device switch from roaming OFF to roaming ON roaming-off - Event triggered when the device switch from roaming ON to roaming OFF roaming-change-country - Event triggered when the device in roaming change country code ' enum: - org.camaraproject.device-roaming-status-subscriptions.v0.roaming-status - org.camaraproject.device-roaming-status-subscriptions.v0.roaming-on - org.camaraproject.device-roaming-status-subscriptions.v0.roaming-off - org.camaraproject.device-roaming-status-subscriptions.v0.roaming-change-country config: description: 'Implementation-specific configuration parameters needed by the subscription manager for acquiring events. In CAMARA we have predefined attributes like `subscriptionExpireTime`, `subscriptionMaxEvents`, `initialEvent` Specific event type attributes must be defined in `subscriptionDetail` Note: if a request is performed for several event type, all subscribed event will use same `config` parameters. ' type: object required: - subscriptionDetail properties: subscriptionDetail: description: The detail of the requested event subscription. type: object properties: device: description: 'End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators. The developer can choose to provide the below specified device identifiers: * `ipv4Address` * `ipv6Address` * `phoneNumber` * `networkAccessIdentifier` NOTE: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device. ' type: object properties: phoneNumber: description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. type: string pattern: ^\+[1-9][0-9]{4,14}$ networkAccessIdentifier: description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator. type: string ipv4Address: type: object description: 'The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers). If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then the same address should be specified for both publicAddress and privateAddress. If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object) In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone. ' properties: publicAddress: description: A single IPv4 address with no subnet mask type: string format: ipv4 privateAddress: description: A single IPv4 address with no subnet mask type: string format: ipv4 publicPort: description: TCP or UDP port number type: integer minimum: 0 maximum: 65535 anyOf: - required: - publicAddress - privateAddress - required: - publicAddress - publicPort ipv6Address: description: 'The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix). ' type: string format: ipv6 minProperties: 1 subscriptionExpireTime: type: string format: date-time description: The subscription expiration time (in date-time format) requested by the API consumer. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. subscriptionMaxEvents: type: integer description: Identifies the maximum number of event reports to be generated (>=1) requested by the API consumer - Once this number is reached, the subscription ends. minimum: 1 initialEvent: type: boolean description: 'Set to `true` by API consumer if consumer wants to get an event as soon as the subscription is created and current situation reflects event request. Example: Consumer request Roaming event. If consumer sets initialEvent to true and device is in roaming situation, an event is triggered. ' id: type: string description: The unique identifier of the subscription in the scope of the subscription manager. When this information is contained within an event notification, this concept SHALL be referred as subscriptionId as per Commonalities Event Notification Model. startsAt: type: string format: date-time description: 'Date when the event subscription will begin/began It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. ' expiresAt: type: string format: date-time description: 'Date when the event subscription will expire. Only provided when `subscriptionExpireTime` is indicated by API client or Telco Operator has specific policy about that. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. ' status: type: string description: "Current status of the subscription - Management of Subscription State engine is not mandatory for now. Note not all statuses may be considered to be implemented. Details:\n\n\n\n\n\n - `ACTIVATION_REQUESTED`: Subscription creation (POST) is triggered but subscription creation process is not finished yet.\n - `ACTIVE`: Subscription creation process is completed. Subscription is fully operative.\n - `INACTIVE`: Subscription is temporarily inactive, but its workflow logic is not deleted.\n - `EXPIRED`: Subscription is ended (no longer active). This status applies when subscription is ended due to `SUBSCRIPTION_EXPIRED` or `ACCESS_TOKEN_EXPIRED` event.\n - `DELETED`: Subscription is ended as deleted (no longer active). This status applies when subscription information is kept (i.e. subscription workflow is no longer active but its meta-information is kept)." enum: - ACTIVATION_REQUESTED - ACTIVE - EXPIRED - INACTIVE - DELETED description: '' '400': content: application/json: examples: GENERIC_400_INVALID_ARGUMENT: description: Invalid Argument. Generic Syntax Exception value: status: 400 code: INVALID_ARGUMENT message: Client specified an invalid argument, request body or query param. GENERIC_400_SUBSCRIPTION_ID_REQUIRED: description: subscription id is required value: status: 400 code: INVALID_ARGUMENT message: 'Expected property is missing: subscriptionId' schema: allOf: - type: object required: - status - code - message properties: status: type: integer description: HTTP response status code code: type: string description: A human-readable code to describe the error message: type: string description: A human-readable description of what the event represents - type: object properties: status: enum: - 400 code: enum: - INVALID_ARGUMENT description: '' '401': content: application/json: examples: GENERIC_401_UNAUTHENTICATED: description: Request cannot be authenticated and a new authentication is required value: status: 401 code: UNAUTHENTICATED message: Request not authenticated due to missing, invalid, or expired credentials. A new authentication is required. schema: allOf: - type: object required: - status - code - message properties: status: type: integer description: HTTP response status code code: type: string description: A human-readable code to describe the error message: type: string description: A human-readable description of what the event represents - type: object properties: status: enum: - 401 code: enum: - UNAUTHENTICATED description: '' '403': content: application/json: examples: GENERIC_403_PERMISSION_DENIED: description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security value: status: 403 code: PERMISSION_DENIED message: Client does not have sufficient permissions to perform this action. schema: allOf: - type: object required: - status - code - message properties: status: type: integer description: HTTP response status code code: type: string description: A human-readable code to describe the error message: type: string description: A human-readable description of what the event represents - type: object properties: status: enum: - 403 code: enum: - PERMISSION_DENIED description: '' '404': content: application/json: examples: GENERIC_404_NOT_FOUND: description: Resource is not found value: status: 404 code: NOT_FOUND message: The specified resource is not found. schema: allOf: - type: object required: - status - code - message properties: status: type: integer description: HTTP response status code code: type: string description: A human-readable code to describe the error message: type: string description: A human-readable description of what the event represents - type: object properties: status: enum: - 404 code: enum: - NOT_FOUND description: '' delete: tags: - Device Roaming Status Subscriptions v0.8 summary: Delete a device-roaming-status event subscription for a device parameters: - name: subscriptionId in: path required: true description: Subscription identifier that was obtained from the create event subscription operation schema: type: string description: The unique identifier of the subscription in the scope of the subscription manager. When this information is contained within an event notification, this concept SHALL be referred as subscriptionId as per Commonalities Event Notification Model. default: qs15-h556-rt89-1298 - name: x-correlator in: header required: false description: Correlation id for the different services schema: {} - $ref: '#/components/parameters/x-rapidapi-host' operationId: deleteDeviceRoamingStatusSubscription-DS-ROS-V080 description: Delete a given device-roaming-status subscription by ID responses: '202': content: application/json: examples: Example_1: value: id: qs15-h556-rt89-1298 schema: description: Response for a device reachability status operation managed asynchronously (Creation or Deletion) type: object required: - id properties: id: type: string description: The unique identifier of the subscription in the scope of the subscription manager. When this information is contained within an event notification, this concept SHALL be referred as subscriptionId as per Commonalities Event Notification Model. description: '' '204': content: application/json: examples: Example_1: value: {} schema: {} description: '' '400': content: application/json: examples: GENERIC_400_INVALID_ARGUMENT: description: Invalid Argument. Generic Syntax Exception value: status: 400 code: INVALID_ARGUMENT message: Client specified an invalid argument, request body or query param. GENERIC_400_SUBSCRIPTION_ID_REQUIRED: description: subscription id is required value: status: 400 code: INVALID_ARGUMENT message: 'Expected property is missing: subscriptionId' schema: allOf: - type: object required: - status - code - message properties: status: type: integer description: HTTP response status code code: type: string description: A human-readable code to describe the error message: type: string description: A human-readable description of what the event represents - type: object properties: status: enum: - 400 code: enum: - INVALID_ARGUMENT description: '' '401': content: application/json: examples: GENERIC_401_UNAUTHENTICATED: description: Request cannot be authenticated and a new authentication is required value: status: 401 code: UNAUTHENTICATED message: Request not authenticated due to missing, invalid, or expired credentials. A new authentication is required. schema: allOf: - type: object required: - status - code - message properties: status: type: integer description: HTTP response status code code: type: string description: A human-readable code to describe the error message: type: string description: A human-readable description of what the event represents - type: object properties: status: enum: - 401 code: enum: - UNAUTHENTICATED description: '' '403': content: application/json: examples: GENERIC_403_PERMISSION_DENIED: description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security value: status: 403 code: PERMISSION_DENIED message: Client does not have sufficient permissions to perform this action. schema: allOf: - type: object required: - status - code - message properties: status: type: integer description: HTTP response status code code: type: string description: A human-readable code to describe the error message: type: string description: A human-readable description of what the event represents - type: object properties: status: enum: - 403 code: enum: - PERMISSION_DENIED description: '' '404': content: application/json: examples: GENERIC_404_NOT_FOUND: description: Resource is not found value: status: 404 code: NOT_FOUND message: The specified resource is not found. schema: allOf: - type: object required: - status - code - message properties: status: type: integer description: HTTP response status code code: type: string description: A human-readable code to describe the error message: type: string description: A human-readable description of what the event represents - type: object properties: status: enum: - 404 code: enum: - NOT_FOUND description: '' /device-status/device-roaming-status-subscriptions/v0.8/subscriptions: get: tags: - Device Roaming Status Subscriptions v0.8 summary: Retrieve a list of device roaming status event subscription parameters: - name: x-correlator in: header required: false description: Correlation id for the different services schema: {} - $ref: '#/components/parameters/x-rapidapi-host' operationId: retrieveDeviceRoamingStatusSubscriptionList-DS-ROS-V080 description: Retrieve a list of device roaming status event subscription(s) responses: '200': content: application/json: examples: List of Subscriptions: description: A list of API consumer subscriptions. If a 3-legged access token is used, the list is specific to the device associated with that token. value: - id: 550e8400-e29b-41d4-a716-446655440000 sink: https://endpoint.example.com/sink protocol: HTTP types: - org.camaraproject.device-roaming-status-subscriptions.v0.roaming-on config: subscriptionDetail: {} subscriptionExpireTime: '2024-07-17T13:18:23.682Z' subscriptionMaxEvents: 5 initialEvent: true startsAt: '2024-07-03T21:12:02.871Z' expiresAt: '2024-07-03T21:12:02.871Z' status: ACTIVE Empty List of Subscriptions: description: The API consumer either has no subscriptions or, if a 3-legged access token is used, has none for the device associated with that token. value: [] schema: type: array minItems: 0 items: description: Represents a event-type subscription. type: object required: - sink - protocol - config - types - id properties: protocol: type: string enum: - HTTP - MQTT3 - MQTT5 - AMQP - NATS - KAFKA description: Identifier of a delivery protocol. Only HTTP is allowed for now sink: type: string format: uri pattern: ^https:\/\/.+$ description: The address to which events shall be delivered using the selected protocol. types: description: "Camara Event types eligible to be delivered by this subscription.\nNote: for the Commonalities meta-release v0.4 we enforce to have only event type per subscription then for following meta-release use of array MUST be decided\n\n\n\n\n\n at API project level.\n" type: array minItems: 1 maxItems: 1 items: type: string description: 'roaming-status - Event triggered when the device switch from roaming ON to roaming OFF and conversely roaming-on - Event triggered when the device switch from roaming OFF to roaming ON roaming-off - Event triggered when the device switch from roaming ON to roaming OFF roaming-change-country - Event triggered when the device in roaming change country code ' enum: - org.camaraproject.device-roaming-status-subscriptions.v0.roaming-status - org.camaraproject.device-roaming-status-subscriptions.v0.roaming-on - org.camaraproject.device-roaming-status-subscriptions.v0.roaming-off - org.camaraproject.device-roaming-status-subscriptions.v0.roaming-change-country config: description: 'Implementation-specific configuration parameters needed by the subscription manager for acquiring events. In CAMARA we have predefined attributes like `subscriptionExpireTime`, `subscriptionMaxEvents`, `initialEvent` Specific event type attributes must be defined in `subscriptionDetail` Note: if a request is performed for several event type, all subscribed event will use same `config` parameters. ' type: object required: - subscriptionDetail properties: subscriptionDetail: description: The detail of the requested event subscription. type: object properties: device: description: 'End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators. The developer can choose to provide the below specified device identifiers: * `ipv4Address` * `ipv6Address` * `phoneNumber` * `networkAccessIdentifier` NOTE: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device. ' type: object properties: phoneNumber: description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. type: string pattern: ^\+[1-9][0-9]{4,14}$ networkAccessIdentifier: description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator. type: string ipv4Address: type: object description: 'The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers). If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then the same address should be specified for both publicAddress and privateAddress. If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object) In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone. ' properties: publicAddress: description: A single IPv4 address with no subnet mask type: string format: ipv4 privateAddress: description: A single IPv4 address with no subnet mask type: string format: ipv4 publicPort: description: TCP or UDP port number type: integer minimum: 0 maximum: 65535 anyOf: - required: - publicAddress - privateAddress - required: - publicAddress - publicPort ipv6Address: description: 'The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix). ' type: string format: ipv6 minProperties: 1 subscriptionExpireTime: type: string format: date-time description: The subscription expiration time (in date-time format) requested by the API consumer. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. subscriptionMaxEvents: type: integer description: Identifies the maximum number of event reports to be generated (>=1) requested by the API consumer - Once this number is reached, the subscription ends. minimum: 1 initialEvent: type: boolean description: 'Set to `true` by API consumer if consumer wants to get an event as soon as the subscription is created and current situation reflects event request. Example: Consumer request Roaming event. If consumer sets initialEvent to true and device is in roaming situation, an event is triggered. ' id: type: string description: The unique identifier of the subscription in the scope of the subscription manager. When this information is contained within an event notification, this concept SHALL be referred as subscriptionId as per Commonalities Event Notification Model. startsAt: type: string format: date-time description: 'Date when the event subscription will begin/began It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. ' expiresAt: type: string format: date-time description: 'Date when the event subscription will expire. Only provided when `subscriptionExpireTime` is indicated by API client or Telco Operator has specific policy about that. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. ' status: type: string description: "Current status of the subscription - Management of Subscription State engine is not mandatory for now. Note not all statuses may be considered to be implemented. Details:\n\n\n\n\n\n - `ACTIVATION_REQUESTED`: Subscription creation (POST) is triggered but subscription creation process is not finished yet.\n - `ACTIVE`: Subscription creation process is completed. Subscription is fully operative.\n - `INACTIVE`: Subscription is temporarily inactive, but its workflow logic is not deleted.\n - `EXPIRED`: Subscription is ended (no longer active). This status applies when subscription is ended due to `SUBSCRIPTION_EXPIRED` or `ACCESS_TOKEN_EXPIRED` event.\n - `DELETED`: Subscription is ended as deleted (no longer active). This status applies when subscription information is kept (i.e. subscription workflow is no longer active but its meta-information is kept)." enum: - ACTIVATION_REQUESTED - ACTIVE - EXPIRED - INACTIVE - DELETED description: '' '400': content: application/json: examples: GENERIC_400_INVALID_ARGUMENT: description: Invalid Argument. Generic Syntax Exception value: status: 400 code: INVALID_ARGUMENT message: Client specified an invalid argument, request body or query param. schema: allOf: - type: object required: - status - code - message properties: status: type: integer description: HTTP response status code code: type: string description: A human-readable code to describe the error message: type: string description: A human-readable description of what the event represents - type: object properties: status: enum: - 400 code: enum: - INVALID_ARGUMENT description: '' '401': content: application/json: examples: GENERIC_401_UNAUTHENTICATED: description: Request cannot be authenticated and a new authentication is required value: status: 401 code: UNAUTHENTICATED message: Request not authenticated due to missing, invalid, or expired credentials. A new authentication is required. schema: allOf: - type: object required: - status - code - message properties: status: type: integer description: HTTP response status code code: type: string description: A human-readable code to describe the error message: type: string description: A human-readable description of what the event represents - type: object properties: status: enum: - 401 code: enum: - UNAUTHENTICATED description: '' '403': content: application/json: examples: GENERIC_403_PERMISSION_DENIED: description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security value: status: 403 code: PERMISSION_DENIED message: Client does not have sufficient permissions to perform this action. schema: allOf: - type: object required: - status - code - message properties: status: type: integer description: HTTP response status code code: type: string description: A human-readable code to describe the error message: type: string description: A human-readable description of what the event represents - type: object properties: status: enum: - 403 code: enum: - PERMISSION_DENIED description: '' post: tags: - Device Roaming Status Subscriptions v0.8 summary: Create a device roaming status event subscription for a device parameters: - name: x-correlator in: header required: false description: Correlation id for the different services schema: {} - $ref: '#/components/parameters/x-rapidapi-host' operationId: createDeviceRoamingStatusSubscription-DS-ROS-V080 description: Create a device roaming status event subscription for a device responses: '201': content: application/json: examples: Active Subscription With Device Disambiguation: value: id: 550e8400-e29b-41d4-a716-446655440000 sink: https://endpoint.example.com/sink protocol: HTTP types: - org.camaraproject.device-roaming-status-subscriptions.v0.roaming-on config: subscriptionDetail: device: phoneNumber: '+99999991000' subscriptionExpireTime: '2024-07-17T13:18:23.682Z' subscriptionMaxEvents: 5 initialEvent: true startsAt: '2024-07-03T21:12:02.871Z' expiresAt: '2024-07-03T21:12:02.871Z' status: ACTIVE Active Subscription: value: id: 550e8400-e29b-41d4-a716-446655440000 sink: https://endpoint.example.com/sink protocol: HTTP types: - org.camaraproject.device-roaming-status-subscriptions.v0.roaming-on config: subscriptionDetail: {} subscriptionExpireTime: '2024-07-17T13:18:23.682Z' subscriptionMaxEvents: 5 initialEvent: true startsAt: '2024-07-03T21:12:02.871Z' expiresAt: '2024-07-03T21:12:02.871Z' status: ACTIVE schema: description: Represents a event-type subscription. type: object required: - sink - protocol - config - types - id properties: protocol: type: string enum: - HTTP - MQTT3 - MQTT5 - AMQP - NATS - KAFKA description: Identifier of a delivery protocol. Only HTTP is allowed for now sink: type: string format: uri pattern: ^https:\/\/.+$ description: The address to which events shall be delivered using the selected protocol. types: description: "Camara Event types eligible to be delivered by this subscription.\nNote: for the Commonalities meta-release v0.4 we enforce to have only event type per subscription then for following meta-release use of array MUST be decided\n\n\n\n\n\n at API project level.\n" type: array minItems: 1 maxItems: 1 items: type: string description: 'roaming-status - Event triggered when the device switch from roaming ON to roaming OFF and conversely roaming-on - Event triggered when the device switch from roaming OFF to roaming ON roaming-off - Event triggered when the device switch from roaming ON to roaming OFF roaming-change-country - Event triggered when the device in roaming change country code ' enum: - org.camaraproject.device-roaming-status-subscriptions.v0.roaming-status - org.camaraproject.device-roaming-status-subscriptions.v0.roaming-on - org.camaraproject.device-roaming-status-subscriptions.v0.roaming-off - org.camaraproject.device-roaming-status-subscriptions.v0.roaming-change-country config: description: 'Implementation-specific configuration parameters needed by the subscription manager for acquiring events. In CAMARA we have predefined attributes like `subscriptionExpireTime`, `subscriptionMaxEvents`, `initialEvent` Specific event type attributes must be defined in `subscriptionDetail` Note: if a request is performed for several event type, all subscribed event will use same `config` parameters. ' type: object required: - subscriptionDetail properties: subscriptionDetail: description: The detail of the requested event subscription. type: object properties: device: description: 'End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators. The developer can choose to provide the below specified device identifiers: * `ipv4Address` * `ipv6Address` * `phoneNumber` * `networkAccessIdentifier` NOTE: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device. ' type: object properties: phoneNumber: description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. type: string pattern: ^\+[1-9][0-9]{4,14}$ networkAccessIdentifier: description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator. type: string ipv4Address: type: object description: 'The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers). If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then the same address should be specified for both publicAddress and privateAddress. If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object) In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone. ' properties: publicAddress: description: A single IPv4 address with no subnet mask type: string format: ipv4 privateAddress: description: A single IPv4 address with no subnet mask type: string format: ipv4 publicPort: description: TCP or UDP port number type: integer minimum: 0 maximum: 65535 anyOf: - required: - publicAddress - privateAddress - required: - publicAddress - publicPort ipv6Address: description: 'The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix). ' type: string format: ipv6 minProperties: 1 subscriptionExpireTime: type: string format: date-time description: The subscription expiration time (in date-time format) requested by the API consumer. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. subscriptionMaxEvents: type: integer description: Identifies the maximum number of event reports to be generated (>=1) requested by the API consumer - Once this number is reached, the subscription ends. minimum: 1 initialEvent: type: boolean description: 'Set to `true` by API consumer if consumer wants to get an event as soon as the subscription is created and current situation reflects event request. Example: Consumer request Roaming event. If consumer sets initialEvent to true and device is in roaming situation, an event is triggered. ' id: type: string description: The unique identifier of the subscription in the scope of the subscription manager. When this information is contained within an event notification, this concept SHALL be referred as subscriptionId as per Commonalities Event Notification Model. startsAt: type: string format: date-time description: 'Date when the event subscription will begin/began It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. ' expiresAt: type: string format: date-time description: 'Date when the event subscription will expire. Only provided when `subscriptionExpireTime` is indicated by API client or Telco Operator has specific policy about that. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. ' status: type: string description: "Current status of the subscription - Management of Subscription State engine is not mandatory for now. Note not all statuses may be considered to be implemented. Details:\n\n\n\n\n\n - `ACTIVATION_REQUESTED`: Subscription creation (POST) is triggered but subscription creation process is not finished yet.\n - `ACTIVE`: Subscription creation process is completed. Subscription is fully operative.\n - `INACTIVE`: Subscription is temporarily inactive, but its workflow logic is not deleted.\n - `EXPIRED`: Subscription is ended (no longer active). This status applies when subscription is ended due to `SUBSCRIPTION_EXPIRED` or `ACCESS_TOKEN_EXPIRED` event.\n - `DELETED`: Subscription is ended as deleted (no longer active). This status applies when subscription information is kept (i.e. subscription workflow is no longer active but its meta-information is kept)." enum: - ACTIVATION_REQUESTED - ACTIVE - EXPIRED - INACTIVE - DELETED description: '' '202': content: application/json: examples: Example_1: value: id: qs15-h556-rt89-1298 schema: description: Response for a device reachability status operation managed asynchronously (Creation or Deletion) type: object required: - id properties: id: type: string description: The unique identifier of the subscription in the scope of the subscription manager. When this information is contained within an event notification, this concept SHALL be referred as subscriptionId as per Commonalities Event Notification Model. description: '' '400': content: application/json: examples: GENERIC_400_INVALID_PROTOCOL: description: Invalid protocol for events subscription management value: status: 400 code: INVALID_PROTOCOL message: Only HTTP is supported GENERIC_400_INVALID_SINK: description: Invalid sink value value: status: 400 code: INVALID_SINK message: sink not valid for the specified protocol GENERIC_400_INVALID_CREDENTIAL: description: Invalid sink credential type value: status: 400 code: INVALID_CREDENTIAL message: Only Access token is supported GENERIC_400_INVALID_ARGUMENT: description: Invalid Argument. Generic Syntax Exception value: status: 400 code: INVALID_ARGUMENT message: Client specified an invalid argument, request body or query param. GENERIC_400_OUT_OF_RANGE: description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested value: status: 400 code: OUT_OF_RANGE message: Client specified an invalid range. GENERIC_400_INVALID_TOKEN: description: Invalid token type for sink credential of type ACCESSTOKEN value: status: 400 code: INVALID_TOKEN message: Only bearer token is supported schema: allOf: - type: object required: - status - code - message properties: status: type: integer description: HTTP response status code code: type: string description: A human-readable code to describe the error message: type: string description: A human-readable description of what the event represents - type: object properties: status: enum: - 400 code: enum: - INVALID_ARGUMENT - OUT_OF_RANGE - INVALID_PROTOCOL - INVALID_CREDENTIAL - INVALID_TOKEN - INVALID_SINK description: '' '401': content: application/json: examples: GENERIC_401_UNAUTHENTICATED: description: Request cannot be authenticated and a new authentication is required value: status: 401 code: UNAUTHENTICATED message: Request not authenticated due to missing, invalid, or expired credentials. A new authentication is required. schema: allOf: - type: object required: - status - code - message properties: status: type: integer description: HTTP response status code code: type: string description: A human-readable code to describe the error message: type: string description: A human-readable description of what the event represents - type: object properties: status: enum: - 401 code: enum: - UNAUTHENTICATED description: '' '403': content: application/json: examples: GENERIC_403_PERMISSION_DENIED: description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security value: status: 403 code: PERMISSION_DENIED message: Client does not have sufficient permissions to perform this action. GENERIC_403_SUBSCRIPTION_MISMATCH: description: Inconsistent access token for requested subscription value: status: 403 code: SUBSCRIPTION_MISMATCH message: Inconsistent access token for requested events subscription schema: allOf: - type: object required: - status - code - message properties: status: type: integer description: HTTP response status code code: type: string description: A human-readable code to describe the error message: type: string description: A human-readable description of what the event represents - type: object properties: status: enum: - 403 code: enum: - PERMISSION_DENIED - SUBSCRIPTION_MISMATCH description: '' '409': content: application/json: examples: GENERIC_409_ABORTED: description: Concurreny of processes of the same nature/scope value: status: 409 code: ABORTED message: Concurrency conflict. GENERIC_409_ALREADY_EXISTS: description: Trying to create an existing resource value: status: 409 code: ALREADY_EXISTS message: The resource that a client tried to create already exists. schema: allOf: - type: object required: - status - code - message properties: status: type: integer description: HTTP response status code code: type: string description: A human-readable code to describe the error message: type: string description: A human-readable description of what the event represents - type: object properties: status: enum: - 409 code: enum: - ABORTED - ALREADY_EXISTS description: '' '422': content: application/json: examples: GENERIC_422_MISSING_IDENTIFIER: description: An identifier is not included in the request and the device or phone number identification cannot be derived from the 3-legged access token value: status: 422 code: MISSING_IDENTIFIER message: The device cannot be identified. GENERIC_422_UNNECESSARY_IDENTIFIER: description: An explicit identifier is provided when a device or phone number has already been identified from the access token value: status: 422 code: UNNECESSARY_IDENTIFIER message: The device is already identified by the access token. GENERIC_422_MULTIEVENT_SUBSCRIPTION_NOT_SUPPORTED: description: Multi event types subscription is not supported value: status: 422 code: MULTIEVENT_SUBSCRIPTION_NOT_SUPPORTED message: Multi event types subscription not managed GENERIC_422_UNSUPPORTED_IDENTIFIER: description: None of the provided identifiers is supported by the implementation value: status: 422 code: UNSUPPORTED_IDENTIFIER message: The identifier provided is not supported. GENERIC_422_SERVICE_NOT_APPLICABLE: description: Service not applicable for the provided identifier value: status: 422 code: SERVICE_NOT_APPLICABLE message: The service is not available for the provided identifier. schema: allOf: - type: object required: - status - code - message properties: status: type: integer description: HTTP response status code code: type: string description: A human-readable code to describe the error message: type: string description: A human-readable description of what the event represents - type: object properties: status: enum: - 422 code: enum: - SERVICE_NOT_APPLICABLE - MISSING_IDENTIFIER - UNSUPPORTED_IDENTIFIER - UNNECESSARY_IDENTIFIER - MULTIEVENT_SUBSCRIPTION_NOT_SUPPORTED description: '' '429': content: application/json: examples: GENERIC_429_TOO_MANY_REQUESTS: description: Access to the API has been temporarily blocked due to rate or spike arrest limits being reached value: status: 429 code: TOO_MANY_REQUESTS message: Rate limit reached. GENERIC_429_QUOTA_EXCEEDED: description: Request is rejected due to exceeding a business quota limit value: status: 429 code: QUOTA_EXCEEDED message: Out of resource quota. schema: allOf: - type: object required: - status - code - message properties: status: type: integer description: HTTP response status code code: type: string description: A human-readable code to describe the error message: type: string description: A human-readable description of what the event represents - type: object properties: status: enum: - 429 code: enum: - QUOTA_EXCEEDED - TOO_MANY_REQUESTS description: '' requestBody: content: application/json: examples: Create Roaming Status Subscription: value: sink: https://endpoint.example.com/sink sinkCredential: credentialType: ACCESSTOKEN accessToken: xxx accessTokenExpiresUtc: '2024-02-17T16:23:45Z' accessTokenType: bearer protocol: HTTP types: - org.camaraproject.device-roaming-status-subscriptions.v0.roaming-status config: subscriptionDetail: device: phoneNumber: '+99999991000' subscriptionExpireTime: '2023-01-17T13:18:23.682Z' subscriptionMaxEvents: 5 initialEvent: true Create Roaming Change Country Subscription: value: sink: https://endpoint.example.com/sink sinkCredential: credentialType: ACCESSTOKEN accessToken: xxx accessTokenExpiresUtc: '2024-02-17T16:23:45Z' accessTokenType: bearer protocol: HTTP types: - org.camaraproject.device-roaming-status-subscriptions.v0.roaming-change-country config: subscriptionDetail: device: phoneNumber: '+99999991000' subscriptionExpireTime: '2023-01-17T13:18:23.682Z' subscriptionMaxEvents: 5 initialEvent: true Create Roaming On Subscription: value: sink: https://endpoint.example.com/sink sinkCredential: credentialType: ACCESSTOKEN accessToken: xxx accessTokenExpiresUtc: '2024-02-17T16:23:45Z' accessTokenType: bearer protocol: HTTP types: - org.camaraproject.device-roaming-status-subscriptions.v0.roaming-on config: subscriptionDetail: device: phoneNumber: '+99999991000' subscriptionMaxEvents: 5 subscriptionExpireTime: '2023-01-17T13:18:23.682Z' initialEvent: true Create Roaming Off Subscription: value: sink: https://endpoint.example.com/sink sinkCredential: credentialType: ACCESSTOKEN accessToken: xxx accessTokenExpiresUtc: '2024-02-17T16:23:45Z' accessTokenType: bearer protocol: HTTP types: - org.camaraproject.device-roaming-status-subscriptions.v0.roaming-off config: subscriptionDetail: device: phoneNumber: '+99999991000' subscriptionMaxEvents: 5 subscriptionExpireTime: '2023-01-17T13:18:23.682Z' initialEvent: true schema: description: The request for creating a event-type event subscription type: object required: - sink - protocol - config - types properties: protocol: type: string enum: - HTTP - MQTT3 - MQTT5 - AMQP - NATS - KAFKA description: Identifier of a delivery protocol. Only HTTP is allowed for now sink: type: string format: uri pattern: ^https:\/\/.+$ description: The address to which events shall be delivered using the selected protocol. sinkCredential: description: A sink credential provides authentication or authorization information necessary to enable delivery of events to a target. type: object properties: credentialType: type: string enum: - PLAIN - ACCESSTOKEN - REFRESHTOKEN description: 'The type of the credential. Note: Type of the credential - MUST be set to ACCESSTOKEN for now ' required: - credentialType types: description: 'Camara Event types eligible to be delivered by this subscription. Note: for the current Commonalities version (v0.5) only one event type per subscription is allowed, yet in the following releases use of array of event types SHALL be specified without changing this definition. ' type: array minItems: 1 maxItems: 1 items: type: string description: 'roaming-status - Event triggered when the device switch from roaming ON to roaming OFF and conversely roaming-on - Event triggered when the device switch from roaming OFF to roaming ON roaming-off - Event triggered when the device switch from roaming ON to roaming OFF roaming-change-country - Event triggered when the device in roaming change country code ' enum: - org.camaraproject.device-roaming-status-subscriptions.v0.roaming-status - org.camaraproject.device-roaming-status-subscriptions.v0.roaming-on - org.camaraproject.device-roaming-status-subscriptions.v0.roaming-off - org.camaraproject.device-roaming-status-subscriptions.v0.roaming-change-country config: description: 'Implementation-specific configuration parameters needed by the subscription manager for acquiring events. In CAMARA we have predefined attributes like `subscriptionExpireTime`, `subscriptionMaxEvents`, `initialEvent` Specific event type attributes must be defined in `subscriptionDetail` Note: if a request is performed for several event type, all subscribed event will use same `config` parameters. ' type: object required: - subscriptionDetail properties: subscriptionDetail: description: The detail of the requested event subscription. type: object properties: device: description: 'End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators. The developer can choose to provide the below specified device identifiers: * `ipv4Address` * `ipv6Address` * `phoneNumber` * `networkAccessIdentifier` NOTE: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device. ' type: object properties: phoneNumber: description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. type: string pattern: ^\+[1-9][0-9]{4,14}$ networkAccessIdentifier: description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator. type: string ipv4Address: type: object description: 'The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers). If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then the same address should be specified for both publicAddress and privateAddress. If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object) In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone. ' properties: publicAddress: description: A single IPv4 address with no subnet mask type: string format: ipv4 privateAddress: description: A single IPv4 address with no subnet mask type: string format: ipv4 publicPort: description: TCP or UDP port number type: integer minimum: 0 maximum: 65535 anyOf: - required: - publicAddress - privateAddress - required: - publicAddress - publicPort ipv6Address: description: 'The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix). ' type: string format: ipv6 minProperties: 1 subscriptionExpireTime: type: string format: date-time description: The subscription expiration time (in date-time format) requested by the API consumer. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. subscriptionMaxEvents: type: integer description: Identifies the maximum number of event reports to be generated (>=1) requested by the API consumer - Once this number is reached, the subscription ends. minimum: 1 initialEvent: type: boolean description: 'Set to `true` by API consumer if consumer wants to get an event as soon as the subscription is created and current situation reflects event request. Example: Consumer request Roaming event. If consumer sets initialEvent to true and device is in roaming situation, an event is triggered. ' description: '' components: parameters: x-rapidapi-host: name: x-rapidapi-host in: header required: true description: The API's Host value as defined in the RapidAPI Hub. schema: type: string example: network-as-code.p-eu.rapidapi.com securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-rapidapi-key description: Your RapidAPI key x-rapidapi-info: apiVersionId: apiversion_969ae0b0-88c0-4670-9353-9c09d02c076f apiId: api_47e41e89-ab4a-40fa-87de-c528077c9945 x-documentation: tutorials: [] spotlights: [] x-gateways: []