Subscriber API

Specification for REST endpoints via which you may provide subscriber information.
For wireline networks, this information is used to gather statistics broken down by subscriber class and location, and may be used to create traffic classifications.
For all network types, it is added to per-flow statistics
(edr-flow-network-intelligence and edr-flow-network-optimization).

Usage

You can post the subscriber metadata using two endpoints: one to sync all subscribers on the network and the other for single-subscriber updates. It is expected to call the latter (“bulk endpoint”) initially, once, with all subscribers in the network; any subscribers previously added but not present in a bulk request will be expired. Any updates should be communicated as soon as possible via the single-sub endpoint.

Base URL and slugs

All endpoints use the prefix [host]/subscriber-info. Each subscriber data endpoint uses a URL parameter “subscriber type”, which can be either “wireline” or “wireless” depending on the subscriber’s method of connecting with the network. For a typical deployment, this will be the same for every subscriber in the network.

Authentication

First an authentication token should be acquired via the endpoint:

GET [host]/subscriber-info/token

Returns:

• On first call, a token which should be attached to the header of
  subsequent requests (see examples)
• On subsequent requests: status 401; to obtain a new token, the system
  must be manually reset by Cisco.

Errors

Client-side errors will generally return a 4xx status code with an error field describing the problem.
One exception exists when providing multiple subscribers at once (described below).
Server-side errors will return a 5xx status code.

Pagination

Does not apply.

Versioning

This document describes the first version of the Subscriber API offered with the Provider Connectivity Assurance User Experience Platform.

Endpoints

POST /fields

Description

This endpoint is used to configure metadata fields (“Fields API”).
By default, any number of extra fields may be provided through an array, see note in the following section regarding disk usage.
A limit can be set via a manual edit of the software’s boot configuration if necessary.

Note that replacing or reordering previously configured fields will relabel existing data.

Parameter definitions

This endpoint expects a request body containing an array of string field names.
No more than 16 fields may be provided.

Example request & response

curl --request POST [host]/subscriber-info/fields
--header "Content-Type: application/json"--header "Authorization: BEARER [token]"--data '["extraA", "extraB", "extraC"]'

Returns:

• For valid input, status code 200 with body:

  {"success":true}

• For invalid input: status 400 with an error message in the response
  body, example:

  {"error": "too many fields provided, 16 allowed"}

POST /data/[subscriber type]

Description

Accepts either a single JSON subscriber object or an array of such.
One of ipv4 or ipv6 must be provided; the other may be provided, left missing, or set explicitly as null. Fields class and location may not exceed 64 characters (longer will be truncated).

Stat fields may be used without constraint, however users should be mindful
that this will affect disk usage and should aim to keep the total character count
under 256.

Parameter definitions

Request payload may be a single JSON object or an array of objects.
This object contains the following fields:

• DeviceId: string, unique identifier for wireline subscribers
• Imsi: uint64, unique identifier for wireless subscribers per 3GPP specification.
  This is hashed for data privacy, though the traffic processor may be configured to add this to statistic records if desired.
• SubscriberClassification: string, optional (will be truncated to 64 characters)
• AccessEndpoint: string, subscriber location information. Optional for wireline subscribers,
  invalid for wireless subscribers as this field is used for the cell identifier (will be truncated to 64 characters)
• UeIpv4: string, valid ip4 or CIDR block. At least one of ipv4 or ipv6 is required for wireline subscribers.
  Both are invalid for wireless subscribers as these are frequently reassigned
  and data is provided by the MPC if installed.
• UeIpv6: string, valid ip6 or CIDR block
• Extra fields as configured via the Fields API

Example request & response

curl --request POST [host]/subscriber-info/data/wireline
--header "Content-Type: application/json"--header "Authorization: BEARER [token]"--data '[            {                "DeviceId": "subscriber1",                "UeIpv4": "142.52.62.12/31",                "AccessEndpoint": "CVC000125",                "SubscriberClassification": "25MbpsPlus",                "extraA": ... ,            },            {                "DeviceId": "subscriber2",                "UeIpv6": "0000:0000:1110:0ab2:0000:0000:ac15:5115",                "AccessEndpoint": "CVC000126",                "SubscriberClassification": "50Mbps".                "extraA": ... ,            },            ...        ]'

Returns:

• For valid input, status code 200 with body:

  {"success":true}

• For invalid (single subscriber) or malformed (multiple subscribers) input:
  status 400 with an error message in the response body. Example:

  {"success": false, "error": "invalid IPv4 address: 8.8.8.8/40"}

• For properly-formed invalid input (multiple subscribers):
  status 200 with a failed field listing bad subscriber objects. Example:

  {"success": true, "failed": [{"index": 3, "error": "invalid IPv4 address: 8.8.8.8/40"}]}

GET /data/[subscriber type]/[id]

Description

This endpoint is used to retrieve stored data for a specific subscriber.

Parameter definitions

The id path parameter corresponds to DeviceId for wireline subscribers and Imsi for wireless subscribers.

Example request & response

curl --request GET --header "Authorization: BEARER [token]" [host]/subscriber-info/data/subscriber1

• For a subscriber ID which exists, status code 200 with body:

  { "DeviceId": "subscriber1", "UeIpv4": "142.52.62.12/31", "AccessEndpoint": "CVC000125", "SubscriberClassification": "25MbpsPlus", "extraA": ... , }

• For subscriber ID which does not exist, status code 404.

DELETE /data/[subscriber type]/[id]

Description

This endpoint is used to delete stored data for a specific subscriber.
This action is not required by the system, but is provided for compliance with laws such as GDPR.

Parameter definitions

The id path parameter corresponds to DeviceId for wireline subscribers and Imsi for wireless subscribers.

Example request & response

curl --request DELETE --header "Authorization: BEARER [token]" [host]:8082/subscriber-info/[uid]

• For a subscriber ID which exists, status code 200 with body:

  {"success":true}

• For subscriber ID which does not exist, status code 404.