Getting Started
- Server Name/URL/Cluster name must be known.
- The main API path — …/at/nbapi/v1.
- Individual API path. For example; asset types, assets, sensors, etc.
- Authentication is done through the User Credentials. For the procedure, refer here.
- This gives the access_token. You have to use this token for further API calls.
Note: The access_token is valid for 300 seconds (5 minutes).
- Getting the x-tenant-id using the Developer tools of any Browser:
Note: This procedure varies slightly based on the browser and in a future release of IOTD, APIs will be exposed to retrieve this information.
In the Firefox browser, go to Web Developer Tools and click the Network Tab.
Login using your user name and password.
Note: You have to have the Tenant Admin permissions.
After logging in, the following API call is made with the relative path /iam/users/me. This can be viewed by filtering the XHR API calls.
For example, an API call as https://us.ciscoiot.com/iam/users/me gives the response in the following format:
The above API response returns more than one role as per your user access. Each array item has a tenant name and a tenant id, and a role name and a role id. If you have access to only one tenant, then this API response will return the result that has only one item.
You need to pick the tenant id of the respective tenant and use it as the x-tenant-id in the HTTP header for the API requests. This x-tenant-id is mandatory for each API call and it needs to be furnished for each API call.
- After getting the access Token and the x-tenant-id, you have to provide them in headers as shown below:
Authentication & Authorization
- API authentication is done via the access token that is generated by making a call to the /iam/auth/token API
- Authorization is based on the user's role
Access Token Generation
Send a POST request to the following URL with the following json content to get the access_token that can be used to invoke IAV NB APIs.
For Example:
Access token generation json
Example JSON:
Example Access token response
API Versioning
- IAV Northbound APIs will support versioning of APIs using URI path based versioning
- IAV Northbound APIs will have the URI path "/iav/api/v1"
- API version is changed only for Breaking/Backward incompatible changes
- API version will not be changed when backward compatible changes are made
Possible Backward Compatible Changes
- Adding new attributes in JSON output of existing APIs
- Adding support for new query parameters
- Adding new endpoints
Note: Backward compatible changes may be done in a future release and you have to implement their integrations in such a way that their integration will not break by the addition of new fields/params/APIs.
Filtering, Sorting, and Pagination for List/Get APIs
Filtering
The filter query parameter is supported by all List/Get APIs for Filtering.
The following Filter field names can be given for each API:
For example:
- filter=Name=ilike="Temperature Sensor 1"
- filter=ManufacturerName=="Honeywell"
- filter=Model!="AV300"
ASSET_TYPE:
- Name
- CreatedBy
- ModifiedBy
ASSET:
- Name
- Type
- Model
- ModifiedBy
GATEWAYS:
- Name
- Type
- SerialNumber
- Model
- GatewayId
- ModifiedBy
- CreatedBy
- Status
enum-values:
- Inventory
- Unheard
- Heard
- Online
- Offline
LORATP:
SENSORS:
- Name
- Type
- Vendor
- Model
- DisplayModel
- DevEUI
- ModifiedBy
- CreatedBy
- Asset
- AssetName
- Status
enum-values:
- Inventory
- Unheard
- Heard
- Healthy
- Unhealthy
- Offline
Sorting
orderBy query parameter is supported by all List/Get APIs for Sorting.
orderBy specifies the column/attribute name followed by "asc" or "desc" to specify the sort order.
For example:
- orderBy=lastSeenAt
- orderBy=createdTime desc
orderBy is an optional parameter and when not passed, createdTime desc is used as default sorting.
The Filter field names can be given in orderBy query param. Refer to Filtering.
page and size query parameters are supported by all List/Get APIs for Pagination.
- page — this specifies the page number
- size — this specifies the page size
page and size are optional parameters and default values for page, and size are 0 and 10.
Note: Max page size supported and defined in API Spec is 500 for all List/Get APIs.
All List/Get APIs provides pageinfo JSON object as part of the response with the following data:
- totalCount — total number of elements found for the given query/filtering criteria
- page — current page number
- size — page size
- count — number of elements in current page
Northbound APIs
IAV Northbound APIs have the URI path {{SERVER_URL}}/at/nbapi/v1
The following Northbound APIs are supported by IAV:
- AssetType Management APIs
- Asset Management APIs
- Gateway Management APIs
- Lora ThirdParty Sensor Management APIs
- Sensor Management APIs
Additional APIs will be added in a phased manner.
AssetType Management APIs
- Get Asset Types
- Get Asset Type By Id
- Add Asset Type
- Update Asset Type
- Delete Asset Type
Asset Management APIs
- Get Assets
- Get Asset By Id
- Add Asset
- Update Asset
- Delete Asset
- Get Sensors of an Asset
- Assign Sensors to an Asset
- Unassign Sensors from an Asset
- Get Image of an Asset
- Get Thumbnail Image of an Asset
- Update/Upload Image of an Asset
- Delete Image of an Asset
Gateway Management APIs
- Get Gateways
- Add Gateway
- Get Gateway by Id
- Update Gateway
- Delete Gateway
- Get Gateway by Serial Number
- Get Gateway Rx/Tx Histogram
Lora ThirdParty Sensor Management APIs
- Get Lora ThirdParty Sensor Models
- Add Lora ThirdParty Sensor
Sensor Management APIs
- Get Sensors
- Get Sensor By Id
- Get Tabular Telemetry Data for a Sensor — This has a max limit of 2000 records
- Update Sensor
- Delete Sensor
- Get Sensor By DevEUI
- Claim Sensor By DevEUI
- Onboard Sensor
- Get Location Data for a Sensor
- Get Telemetry Data for a Sensor — This has a max limit of 2000 records
Caveats
Following caveats/limitations apply for usage of the NB APIs. These will be removed in future releases.
- For maximum functional reach of API integrations, it is recommended to setup a separate user account designated for API usage assigned with Tenant admin role.
- If a new API user is added with tenant admin role, one of the below steps must be performed to ensure that user has proper access control group assigned in IAV
- Login to IAV Web application as that user - this will initiate a sync for that specific user internally and will associate Full Admin ACG to the user.
- Some other tenant admin can login to IAV Web application and go to the users tab - this will cause sync for all users and all tenant admin users will be assigned Full Admin ACG.
- In case intention is to use some other role (other than an existing Admin role), then,
- When a new user account is created for API access, Tenant admin has to ensure that he or she has to login to IAV Web Application and assign appropriate access control groups (ACG) for the user.
Additional notes:
- API keys cannot be used for accessing the NB APIs. API keys are not associated to any users whereas to access sensor/asset/gateway data within IAV, we would need to know the user who is invoking the API so that we can filter and provide a response based on the access control groups assigned to the user in IAV.
- In case Single-Sign On (SSO) is setup for an organization, then, User account that is used for invoking APIs should be set up so they are excluded from SSO authentication.
Generating Client Bindings
Installing openapi-generator
Instructions for installing openapi-generator can be found at OpenAPI Generator CLI Installation.
For MacOS, run the following command to install:
openapi-generator installation
Java
Run the following command to generate Java Open API Client bindings:
open api client generator java
Python
Run the following command to generate Python Open API Client bindings:
open api client generator python
Example Program
Java
iav nb api client example java program
Python
iav nb api example python program