PSS API Service Calls

Token Activation - Service Calls

This section assumes that you have completed the steps in the PSS API Quick Start Guide (registered the API applications and received the OAuth 2.0 credentials). This section describes the process of developing API service calls and provides access information about the following areas:

• Manual Process Overview for API Service Calls
• PSS API Services
• Message Format

Manual Process Overview for API Service Calls

There are four main parts to the manual API service call process:

• Step 1 Use OAuth 2.0 credentials to obtain an access token.
• Step 2 Get a list of all the customers and their associated inventories.
• Step 3 Select a customer and inventory from previous service call and get all device details for a specific inventory.
• Step 4 Use the information from the first three steps to get the information for all the remaining API service calls.

Back to Top / Back Home

Obtaining Access Token

This is the first step in a four step process of obtaining service call related information. You will get OAuth2.0 credentials after registering an application on API Console. That will include 'Client ID' and 'Client Secret'. This pair needs to be used to get the access token, which can then be used to make API calls.

You can download the PSS Token WADL.xml from the https://apiconsole.cisco.com/docs/pssv1/downloads tab on the PSS APIs site to help you create this API service call.

The following list contains important information about requesting an access token:

• Input must be sent with a content-type of application/x-www-form-urlencoded “with POST Querystring” options.
• All input fields are required.
• The access_token is valid for 3600 seconds (1 hour) from time of creation.
• Output will be in application/json format (JavaScript Object Notation).
• The PSS TOKEN endpoint location is: https://api.cisco.com/pss/token.
• The "access_token" value of this API is to be placed on all subsequent PSS API calls as a http header (i.e., Authorization: Bearer vvbvjgncqpbkyd57cnjuer8g).
• If an access_token expires, you can re-query the /pss/token service for a new access_token at any time, using the same OAuth 2.0 credentials that were used previously. There is no OAuth 2.0 credentials refresh token function available at this time.

Sample code for requesting an access token:

REQUEST

  POST https://api.cisco.com/pss/token HTTP/1.1
  Accept-Encoding: gzip,deflate
  Content-Type: application/x-www-form-urlencoded
  Content-Length: 103
  Host: api.cisco.com
  Connection: Keep-Alive
  User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
  grant_type=client_credentials&client_id=ee8npyz5an6f85rupdb2w8j4&client_secret=XXXXXXMYSECRETXXXXXXXXXX  
            

RESPONSE

  HTTP/1.1 200 OK
  Date: Wed, 10 Apr 2013 01:04:26 GMT
  Server: Mashery Proxy
  X-Mashery-Responder: APIX-PROD-03
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store
  Content-Length: 117
  Connection: close
    {
    "token_type":"bearer",
    "mapi":"yh4xkpx7cbgy6wqynre4wf4r",
    "access_token":"zkqnhau3mwsbr79ns554fx",
    "expires_in":3600
    }
            

Back to Top / Back Home

Get a List of All the Customers

Get a list of all the partner's end customers and their associated inventories that have been uploaded by performing the following step:

• Use the getCustomersInventoryIds API service call and send empty (no) customer id's; the output contains a list of all the customers and their associated inventories.

Input–empty customer ids

Output–the API service call response contains the following attributes:

CustomerInventory[]

• Customer (id,name)
• Inventory (id,name)

Back to Top / Back Home

Get All Device and Card Details for an Inventory

Get a list of all the devices and cards in an inventory by performing the following step:

• Use the getCustomerInventoryDetails API service call to send the customer id and inventory id (from the previous step); the output contains a list of all the devices, cards and their associated information for the specified inventory.

Input–customerId, inventoryId

Output–CustomerInventoryDetailResponseOutput. This object contains the following attributes:

DeviceDetail[]

• – –deviceId
• – –hostName
• – –ipAddress
• – –originalSerialNumber
• – –validatedSerialNumber
• – –productId
• – –productDescription
• – –productFamily
• – –productName
• – –productModel
• – –elementType
• – –cardDetail

Back to Top / Back Home

Use Inventory API Information for Other Service Calls

Use the deviceId, obtained from the preceding steps, to obtain detailed device information in the remaining service call areas:

• Contract
• PSIRT
• IntelliShield
• EOX (HWEox and SWEox)
• Field Notices (FN)

Limitations and Workarounds

If the calling application requests data for more than 10K PIDs, the API will not return any data. The following error message appears: API cannot respond due to big size of inventory.

If the data returned is less than 10K PIDs, and the request takes longer than 2 minutes, a timeout error is thrown.

There are multiple alternatives to avoid hitting this limit. For example, one alternative is to invoke APIs with both the Customer ID and Inventory ID provided to restrict the APIs to only return details for devices that belong to that customer and for that specific inventory of the customer (instead of returning information of all the devices from all the customers of the partner). Another alternative is to call APIs in chunks of 100 Device IDs per API call.