Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Current »

This page guides you through the usage of the AGILITY API to help you get started quickly.


You will learn how to integrate and use the AGILITY API to analyze network traces with ease.

Prerequisites

Please ensure that you have the necessary credentials and permissions to access the API (login ID and password) from your administrator.

Overview

The AGILITY API is designed for system integrators and developers to enable advanced analysis on network traces, specializing in root cause analysis for call flows. The API supports file formats such as .PCAP, .PCAPNG, .CAP, and .ZIP.

API base URL

Use the base URL to access the OpenAPI documentation:

http(s)://<YOUR_PUBLIC_DN>/cv/api/public/docs

(example: https://cv-dev.b-yond.com/cv/api/public/docs ).

Authentication

Use the OAuth2 Password Flow to request an id_token.

Request the token

Endpoint

POST /cv/auth/realms/agility/protocol/openid-connect/token

Provide your username, password, and the client_id (which is public and provided as d0d8b0d806f9) in your request.

Headers

  • Content-Type: application/x-www-form-urlencoded

Body

  • grant_type: password

  • client_id: d0d8b0d806f9

  • username: Your registered user name.

  • password: Your password.

  • scope: openid

Example cURL request

curl -X POST https://cv-dev.b-yond.com/cv/auth/realms/agility/protocol/openid-connect/token \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=password&client_id=d0d8b0d806f9&username=YOUR_USERNAME&password=YOUR_PASSWORD&scope=openid"

Replace YOUR_USERNAME and YOUR_PASSWORD with your credentials.

Response

Upon successful authentication, you'll receive a JSON response containing the id_token among other tokens.

  • Use the value of YOUR_ID_TOKEN in your subsequent API requests as a Bearer Token to authenticate your actions.

  • Use the REFRESH_TOKEN_VALUE to obtain a new token as described in the next section.

{
    "access_token": "ACCESS_TOKEN_VALUE",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "REFRESH_TOKEN_VALUE",
    "id_token": "YOUR_ID_TOKEN",
    ...
}

In the example above, the token expires in 300 second (5 min) while the refresh_token is valid for 1800 second (30 min).

Note: Always keep your id_token, access_token, and refresh_token secure. Do not expose them in client-side scripts or other insecure locations.

Handling expired tokens

When an access token expires, AGILITY API will no longer accept incoming request and will redirect you to the login page. We recommend that you request a new id_token using the refresh token request if it still valid or just re-authenticate.

Use these steps to handle expired tokens and ensure continuous access to the AGILITY API without requiring users to re-authenticate.

To refresh an expired token, follow these steps:

  1. Make a refresh token request: Send a POST request to the token URL with the required parameters to refresh the token. Use the refresh token received during the initial authentication.

    Example Request:

    POST /cv/auth/realms/agility/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=[Your Refresh Token]
&client_id=d0d8b0d806f9

  2. Receive a new id_token: If the refresh token is valid, AGILITY will respond with a new access token and potentially a new refresh token.

    Example Response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "[New Access Token]",
  "expires_in": 300,
  "token_type": "Bearer",
  "refresh_token": "[New Refresh Token]",
  "refresh_expires_in": 1800,
  "id_token": "[New Id Token]",
  // ... other token information
}

  3. Update your authorization: Use the new access token in your request headers for subsequent API requests.

Note: Remember to securely store and manage the refresh token, as it provides long-term access to the API and should be protected from unauthorized access.

AGILITY API endpoints

Retrieve supported services

Endpoint

GET /cv/api/v1/services/

Use this endpoint to fetch a list of supported services.

Parameters

  • page: Specify the page number. (Default: 1)

  • size: Specify the number of results per page. (Default: 50; Maximum: 100)

Example request

curl -X 'GET' \
  'https://cv-dev.b-yond.com/cv/api/v1/services/?page=1&size=50' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_ID_TOKEN'

Start a new analysis

Endpoint

POST /cv/api/v1/analysis/file

This endpoint allows you to initiate an analysis using a supported network trace file.

Request body

  • uploadFile: Upload your network trace file here (the file should be available locally).

  • serviceKeys: (Optional) List of service keys for the analysis. If you're unsure, leave this empty for service auto-discovery.

Example request

curl -X 'POST' \
  'https://cv-dev.b-yond.com/cv/api/v1/analysis/file' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_ID_TOKEN' \
  -H 'Content-Type: multipart/form-data' \
  -F 'uploadFile=@myfile.pcap' \
  -F 'serviceKeys=volte'

Fetch analysis results

Endpoint

GET /cv/api/v1/analysis/{analysis_id}/summary

After initiating an analysis, use this endpoint to retrieve the results.

Parameters

  • analysis_id: The ID of the analysis (received from the previous step).

  • page: (Optional) Specify the page number. (Default: 1)

  • size: (Optional) Specify the number of results per page. (Default: 50; Maximum: 1000)

Example request

curl -X 'GET' \
  'https://cv-dev.b-yond.com/cv/api/v1/analysis/8599e936-19ee-4b13-a9ad-44fecadad9fe/summary?page=1&size=50' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_ID_TOKEN'

  • No labels