Overview
CCAB uses a GraphQL API that allows providers to manage different areas such as the plans, accounts, devices, etc. It isn't necessary to always use the API as most of these areas can be managed through the Plans UI; nevertheless, some might need to use the API in certain scenarios such as when setting up some automation.
This article covers the basic topics around the CCAB API along with a couple of requests as examples.
API Users
Every provider/tenant would have access to different types of users. Each of these users can access different areas of the API as shown below:
- Account Query - Read-only access to tenant accounts and devices.
- Account Admin - Read and write access to tenant accounts and devices.
- Data Admin - Read-only access to tenant accounts, devices, and EDRs.
- Plan Query - Read-only access to plans.
- Plan Designer - Read and write access to plans but no plan deployment.
- Plan Publisher - Read access to plans and deployment of plans.
- Tenant Admin - Read and write access to users.
Therefore, depending on the type of request one plans to use, it would be necessary to Obtain an Access Token using the appropriate user. For instance, if one needs to create new devices, the Device/Account User credentials should be used to obtain an access token.
Note: There is also an Infra/Charging user for the provider that has access to the 5G/Charging API which is different than the Management API. See Understanding the 5G/Charging API for further details.
API Usage
To work with the GraphQL API one can use the tool of their preference for making requests such as Postman, cURL, or some more advanced clients like Apollo or Insomnia.
To work with the API one needs to know their Provider ID as it is required for most operations. Additionally, to make any requests one first needs to Obtain an Access Token. This is done through the AWS Cognito service using the respective user credentials.
Once the access token (IdToken) is obtained, one can proceed with making requests to the API with the following details.
Below are additional resources covering certain API calls.
A full list of all available queries and mutations can be found in the CCAB API Docs.
API Examples
Next, there are a couple of examples in order to provide some further insights on the API requests.
Get Plans
Since we are working with plans we will use the credentials of either Plan Query, Plan Designer, or Plan Publisher when obtaining the access token.
As we can see from the API Documentation, we would need to use the GetPlans query operation which uses 4 different parameters (providerId, first, after, orderBy), and returns a Plan Connection (which consists of a PlanEdge>Plan>PlanVersionConnection). Thus, we need to make sure the query request contains the relevant entries from the response.
For instance, if we want to query the first 10 plans along with up to 10 versions from each plan, the body of our request would be as follows.
#We are only passing the provider and first parameters since the other two are not needed to get the first 10 plans
#Inside the query we are adding the information we want to be part of the response.
#In this scenario we are requesting the id,name and versions of each plan (edge/node)
#And the id and version of each version(up to 10) for the plan
query getPlans{
getPlans(providerId: "providerid", first:10) {
edges {
node{
id
name
versions (first:10){
edges{
node{
id
version
}
}
}
}
}
}
}
The final request would be something similar to:
curl --location --request POST 'https://4c3mrbifgveqpkxnni5fcjhjwi.appsync-api.us-east-1.amazonaws.com/graphql/' \
--header 'Authorization: IdToken' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"query getPlans{getPlans(providerId: \"providerid\", first:10){edges { node {id name versions (first:10){edges {node {id version}}}}}}}"}'
The response would contain the information queried in the request.
Create Device
Since we are working with devices we will use the credentials of our Account Admin when obtaining the access token.
As we can see from the API Documentation, we would need to use the CreateDevice mutation operation which uses a CreateDeviceInput with 4 different parameters (providerId, accountId, device, customData), and returns a Create Device Result which has 4 different types of possible results (CreateDevicePayload, AccountNotFound, DeviceAlreadyExists, InvalidField). Thus, one needs to make sure some of these results are handled as part of the request.
For instance, if we need to create a new device for an account but want to make sure we also receive details in case the account does not exist, the body of our request would be as follows.
#We are only passing the accountid and providerid since we want to get a new device id.
#Inside the query we are adding the information we want to be part of the response such as the device id if successful
#In case the response goes into AccountNotFound we also want the details such as the error message.
mutation createDevice{
createDevice(input: {accountId: "accoundid", providerId: "providerid"}) {
... on CreateDevicePayload {
__typename
device {
id
providerId
account {
id
}
}
}
... on AccountNotFound {
accountId
errorCode
errorMessage
}
}
}
The final request would be something similar to:
curl --location --request POST 'https://4c3mrbifgveqpkxnni5fcjhjwi.appsync-api.us-east-1.amazonaws.com/graphql/' \
--header 'Authorization: IdToken' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation adddevice{ createDevice(input: {accountId: \"accountid\", providerId: \"providerid\"}) {... on CreateDevicePayload { __typename device { id providerId account {id}}} ... on AccountNotFound {accountId errorCode errorMessage}}}"}'
The response would contain the following information if valid.
In case the account id was not valid, it would return the details we requested as part of the payload.
