API Integration Guide

XGP allows external services to integrate with XGP via API integration point. For example, CI/CD pipelines can invoke XGP integration APIs under their test stage to execution scenarios to validate their deployments.

Execute API

API to trigger executions on a selected device, where this API also can be used to specifically run a test on a specific module of a device.

API URL

POST baseurl/execution

Request Payload

{
 "environmentName": "XG-001-312",
 "module": "3",
 "sim": "1",
 "ApplicationId": "4da85f64-acd7-4562-b3fc-2c9ab1f622f1",
 "scenarios":
    [
      "Call Receiver",
      "Call Forward",
    ] 
}

EnvironmentName -- A unique environment name that identifies each device separately.

  • module -- module number of the module.

  • Sim -- sim number of the module.

  • ApplicationId -- The application Id of the executing scenarios.

  • Scenarios -- List of scenario names being executed. (Note: Name should exactly match the scenario name available in the system and should be alphanumeric only)

Response

{
 "executions":    {
       "executionId": "4da85f64-acd7-4562-b3fc-2c9ab1f622f1",
       "status": " Execution Stated",
    }
"timeStamp": "2020-06-15T17:37:23.185Z"
}

  • ExecutionId -- A unique Id for this execution.

  • Status -- Device/Execution status. Possible statuses are as follows

    • Execution Stated

    • Device Busy

    • Device offline

  • Timestamp -- Execution timestamp

Execute API (With Template)

API to trigger executions on a selected device using a execution template Id which can be configured on the XG Portal.

API URL

POST baseurl/execution/template/:id

Route Parameter

 "id": "4da85f64-acd7-4562-b3fc-2c9ab1f622f1"
  • TemplateId -- Id of the template which contains all the information required for an execution

Response

{
 "executions":    {
       "executionId": "4da85f64-acd7-4562-b3fc-2c9ab1f622f1",
       "status": " Execution Stated",
    }
"timeStamp": "2020-06-15T17:37:23.185Z"
}

  • ExecutionId -- A unique Id for this execution.

  • Status -- Device/Execution status. Possible statuses are as follows

    • Execution Stated

    • Device Busy

    • Device offline

  • Timestamp -- Execution timestamp

Check Status API

This API can be used to check status of each execution and return the status with the time stamp. This can be used to get live update by calling it frequently.

Request

API URL

GET baseurl/execution/:Id/status

Payload

"Id" : "a887bcb3-e281-480e-a73e-76220ee57142"
  • Id -- Id of the current execution.

Response

200 OK

Returns an object which has status and Timestamp in UTC. The status property will return the status of the execution and it can hold the following values.

  • Initiated -- When the execution is triggered and added to queue

  • Started -- When the execution is started

  • InProgress -- while the execution is processing

  • Complete -- When the execution is completed

  • Error -- When an exception occurs

{
  "status": "InProgress",
  "timeStamp": "2022-06-15T17:37:23.185Z",
 }

  • Content -- Body of the SMS

  • Timestamp -- the request timestamp

Get Result API

This API would be used to get the final result once the status API returns "Completed".

Request

API URL

GET baseurl/execution/:Id/result

Route Parameter

"Id" : "a887bcb3-e281-480e-a73e-76220ee57142"

Id -- Id of the completed execution.

Response

200 OK

Returns an object which has status and Timestamp in UTC. The status property will return the status of the execution and it can hold the following values.

  • Initiated -- When the execution is triggered and added to queue

  • Started -- When the is execution started

  • InProgress -- while the execution is processing

  • Complete -- When the execution is completed

  • Error -- When an exception occurs

{
  "status": "InProgress",
  "executionLog": 
     [ 
        "string" 
     ]
  "timeStamp": "2022-06-15T17:37:23.185Z",
 }

  • Content -- Body of the SMS

  • Result -- Result object

  • Timestamp -- the request timestamp

Invalid Responses

The following are the common responses when the API request is not success.

400 Bad Request

Request has malformed input

401 Unauthorized

When an error occurs while authenticating, additional details are returned in www-authenticate header.

www-authenticate: Bearer

No authentication scheme specified. API will instruct the scheme to be used for authentication

www-authenticate: Bearer error=\"invalid_token\",
error_description=\"The token is expired\"

Token is provided but expired.

www-authenticate: Bearer error="invalid_token", error_description="The signature is invalid"

Invalid token provided

408 Request Timeout

A successful execution response was not received from test environment within the specified timeout. This could mean the device is offline or unresponsive.

409 Conflict

Device is busy. An execution is already running in the target device/module and the request is rejected.

500 Internal Server Error

An internal error is preventing the execution

Authentication

We will be using the OAuth2 Client Credentials flow for authenticating the API. All API requests expect a valid access token to be sent with the request. The token flow is illustrated below.

Authenticate flow

Authenticate with Client Id + Client Secret (Request token)

Request URL

POST identity_service_url/connect/token Request

Payload (Body FormData)

client_id={client_id} 
client_secret={secret}
grant_type=client_credentials 
scope=drc_dev

The identity_service_url, client id and client secret will have been delivered to you in other medium.

Response

{
  "access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRw…...",
  "expires_in":3600,
  "token_type":"Bearer"
}

Use the returned access_token in subsequent requests as a bearer token. Note that the access token will expire in the time(seconds) specified in expires_in response.

Request Header

Authorization: Bearer