Skip to content

Latest commit

 

History

History
87 lines (59 loc) · 9.34 KB

Connectivity_API.md

File metadata and controls

87 lines (59 loc) · 9.34 KB

Overview

This API makes possible to query the connectivity status of user equipment.

1. Introduction

2. Quick Start

DeviceStatus API v0.2.0 exposes only one endpoint, which can be used to check connectivity status for user equipment. To do so user has to pass following parameters in request body:

  1. ueId - an object with four fields, each of them make possible to pass ueId in different format: externalId [1], msisdn, ipv4Addr and ipv6Addr
  2. uePort - if a public ipv4Addr is provided for the ueId object, the port allocated to the UE must also be specified
  3. eventType - string value which determines the connectivity event to check its status, for now only "UE_ROAMING_STATUS" is supported.

Sample API invocation is presented in Section 4.4.

3. Authentication and Authorization

The Device Status API makes use of the 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 [2].

4. API Documentation

The API user wants to execute a check of connectivity status for a user equipment. The current API version make possible to check only the roaming status of device with given identifier. It can be extended in the future with other event types.

4.1 Endpoint Definitions

Following table defines API endpoints of exposed REST based for device status query operations.

Endpoint Operation Description
POST
<base-url>/connectivity/v0/status		 Device Connectivity Status Get the current connectivity status

Check device connectivity status

Execute check of device connectivity status
HTTP Request
POST <base-url>/connectivity/v0/status
QueryParameters
No query parameters are defined.
Path Parameters
No path parameters are defined.
Request Body Parameters
ueId: UE identifier object, contains 4 different identifiers, at least 1 has to be set
uePort (optional): User equipment port. Device port may be required along with IP address to identify the target device
eventType: enum type value, for now only one is supported: UE_ROAMING_STATUS

Response
200: Connectivity status checked
Response body:
ueId: UE identifier object, contains 4 different identifiers, at least 1 has to be set
uePort (optional): User equipment port. Device port may be required along with IP address to identify the target device
eventType: enum type value, contains UE_ROAMING_STATUS
eventStatus: enum type value, contains one of the following: ROAMING_ON, ROAMING_OFF

400: Invalid input.
401: Un-authorized, missing or incorrect authentication.
403: Forbidden access.
404: Resource not found.
500: Server error.
503: Service temporarily unavailable.

4.2 Errors

Since CAMARA Device Status API is based on REST design principles and blueprints, well defined HTTP status codes and families specified by community are followed [3].

Details of HTTP based error/exception codes for the Device Status API are described in Section 4.2 of each API REST based method. Following table provides an overview of common error names, codes and messages applicable to Device Status API.

No Error Name Error Code Error Message
1 Invalid port(s) 400 "Ports specification not valid"
2 Invalid ueId 400 "Validation failed for parameter: ueId"
3 Invalid port 400 "Validation failed for parameter: port"
4 Invalid eventType 400 "Validation failed for parameter: eventType"
7 Unauthorized 401 "Un-authorized to invoke operation"
8 Forbidden 403 "Forbidden to invoke operation"
9 Not found 404 "The specified resource is not found"
10 Internal server error 500 "Internal server error"
11 Service unavailable 503 “Internal error due to required telco service unavailability"

4.3 Policies

N/A

4.4 Code Snippets

Snippet 1. Execute location verification
curl -X 'POST' https://sample-base-url/connectivity/v0/status
-H 'accept: application/json'
-H 'Content-Type: application/json'
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...."
-d '{
"ueId": {
"externalId": "[email protected]",
"msisdn": "41793834315",
"ipv4Addr": "192.0. 2.146",
"ipv6Addr": "2001:db8:3333:4444:5555:6666:7777:8888"
},
"port": 5060,
"eventType": "UE_ROAMING_STATUS"
}

4.5 FAQ's

(FAQs will be added in a later version of the documentation)

4.6 Terms

N/A

4.7 Release Notes

N/A

References

[1] External Identifier format of the GPSI https://github.com/camaraproject/WorkingGroups/blob/main/Commonalities/documentation/UE-Identification.md#external-identifier-format-of-the-gpsi
[2] Camara Commonalities : Authentication and Authorization Concept for Service APIs https://github.com/camaraproject/WorkingGroups/blob/main/Commonalities/documentation/Working/CAMARA-AuthN-AuthZ-Concept.md
[3] HTTP Status codes spec https://restfulapi.net/http-status-codes