FI-WARE OAUTH-XACML-based API Access Control - Overview (Part 1)
Cisco Device Activations RC Provisioning API · All the services are currently exposed through the...
Transcript of Cisco Device Activations RC Provisioning API · All the services are currently exposed through the...
CISCO DEVICE ACTIVATIONS
RC PROVISIONING API
11/17/2017 RC PROVISIONING API SPEC
1
Contents 1 Introduction ........................................................................................................................................... 3
2 Service Authentication........................................................................................................................... 3
2.1 First Time Access .............................................................................................................. 3 2.1.1 API Manager Portal .................................................................................................................. 3
2.2 Creating client Applications .............................................................................................. 4 3 API Requirements ................................................................................................................................ 10
3.1 Assign Mac Address ........................................................................................................ 10 3.1.1 Request URI ............................................................................................................................ 10
3.1.2 Query Parameters .................................................................................................................. 11
3.1.3 Request Header ..................................................................................................................... 11
3.1.4 Response Attributes ............................................................................................................... 11
3.1.5 Response Body ....................................................................................................................... 13
3.1.6 Sample Response Body .......................................................................................................... 13
3.2 Retrieve Profile ................................................................................................................ 15 3.2.1 Request URI ............................................................................................................................ 15
3.2.2 Query Parameters .................................................................................................................. 15
3.2.3 Request Header ..................................................................................................................... 15
3.2.4 Response Attributes ............................................................................................................... 15
3.2.5 Response Body ....................................................................................................................... 16
3.2.6 Sample Response Body .......................................................................................................... 16
3.3 Disassociate MAC from a profile .................................................................................... 17 3.3.1 Request URI ............................................................................................................................ 17
3.3.2 Query Parameters .................................................................................................................. 17
3.3.3 Request Header ..................................................................................................................... 17
3.3.4 Response Attributes ............................................................................................................... 17
3.3.5 Response Body ....................................................................................................................... 18
3.3.6 Sample Response Body .......................................................................................................... 18
3.4 Get Devices for a Profile ................................................................................................. 19 3.4.1 Request URI ............................................................................................................................ 19
3.4.2 Query Parameters .................................................................................................................. 19
3.4.3 Request Header ..................................................................................................................... 19
3.4.4 Response Attributes ............................................................................................................... 19
11/17/2017 RC PROVISIONING API SPEC
2
3.4.1 Response Body ....................................................................................................................... 20
3.4.1 Sample Response Body .......................................................................................................... 20
4 Appendix .............................................................................................................................................. 21
4.1 Request Headers .............................................................................................................. 21 4.2 Error codes:...................................................................................................................... 21 4.3 Generic Exceptions: ......................................................................................................... 21
11/17/2017 RC PROVISIONING API SPEC
3
1 Introduction
This document aims in detailing the API specifications for the CDA (Cisco Device Activations)
Rest services to setup redirection for your devices.
2 Service Authentication All the services are currently exposed through the mule API gateway. This uses OAuth for
service authentication. Access tokens have a lifetime of 1 hour and there is a limit to the number
of tokens that can be generated per day.
The expectation is for the consumers to cache the access tokens and generate them only when
needed.
2.1 First Time Access
Prerequisites:
1. You have an existing cisco.com account. To register go to:
https://idreg.cloudapps.cisco.com/idreg/guestRegistration.do?locale=en_US&exit_url=
2. Your cisco.com account has access on CDA / EDOS web portal
(https://webapps.cisco.com/software/edos/home) as “Distributed Customer” role. If not,
you can request access there by logging in with your cisco.com account.
Note: If you already have an access for different type of role, you can email to cdap-
[email protected] for help. Please make sure you specify your cisco.com user id (could
be different from your email address) when reaching out to support team.
3. You have redirection profile created under Profile Management section of the CDA /
EDOS web portal.
Send an email to “[email protected]” to provide the VIEW and ENTITLE access to the “RC Provisioning” API in production environment.
2.1.1 API Manager Portal
API Portal is used to create client applications, get the client_key and client_secret, and then
associate your client applications to API's.
• API Portal: https://anypoint.mulesoft.com/apiplatform/apx/#/portals
11/17/2017 RC PROVISIONING API SPEC
4
2.2 Creating client Applications
1. Select the API under which client application has to be created. In this case,
search for “RC” and from search results, please click on RC Provisioning.
11/17/2017 RC PROVISIONING API SPEC
5
2. Click on “Request API access” to create new Application under the API’s.
3. Create a New Application by clicking on New Application button.
4. Fill the Application name, OATH2.0 grant type as “Resource Owner Grant” , select the last checkbox and click on ADD.
11/17/2017 RC PROVISIONING API SPEC
6
5. Client Application will be created and will be listed out in API applications list
in DASHBOARD. Once the application is successfully created you will get an email notification with your application name along with client ID/Secret associated with it.
11/17/2017 RC PROVISIONING API SPEC
7
6. Application name will be available in drop down.
7. Now select the application you created from the drop down list, accept the terms and then request access to the API.
8. This will ensure that your client application is associated with the API and you can provide client id/secret to your customers to generate an Oauth token and pass it as a header for authorization while accessing your API. Click on ok.
11/17/2017 RC PROVISIONING API SPEC
8
9. Customer will be able to see their Client Apps under My Applications tab as
shown below.
10. You can access your Client ID and Client Secret by clicking the app under My
applications. Once you click on your app, you will be able to see the client id and client secret.
11/17/2017 RC PROVISIONING API SPEC
9
11. Once the contract is approved, Customer will get a contract approval email. After contract approval, customers will be able to generate Token using Token generation service.
•
11/17/2017 RC PROVISIONING API SPEC
10
Service to generate the Token :
HTTP method POST
HOST https://cloudsso.cisco.com
Context path /as/token.oauth2
Query Params grant_type=password&client_id=<clientId>&client_secret=<clientSecret>&username=<userName>&password=<password>
Response {"access_token":"<accessToken>","token_type":"Bearer","expires_in":3599}
URL https://cloudsso.cisco.com/as/token.oauth2?grant_type=password&client_id=<clientId>&client_secret=<clientSecret>&username=<Cisco.com user ID>&password=<Cisco.com password>
3 API Requirements
3.1 Assign Mac Address
This service will be used to assign the mac address to a profile name/id.
3.1.1 Request URI
POST https://apx.cisco.com/cdasvcs/api/rc/v1/addMacAddr
POST {"profileName":"test-profile","soldTo":"123456789","shipTo":"234567890","macAddress":["105F4965E096","105F4965E10E","BAC7E70ECA4B","8E4D2D890CD8","B2CEDB5DEE7"], "overrideRequest":"Y"}
11/17/2017 RC PROVISIONING API SPEC
11
3.1.2 Query Parameters
Name Description Format Mandatory(Y/N)
profileName Profile to assign String
Y
soldTo Sold to associated to the macaddress .It can be
passed as blank for Distributed Customer.
String
N
shipTo Ship To associated to the macaddress. It can be
passed as blank for Distributed Customer.
String N
macAddress Mac to which profile needs to be assigned.
List
Y
overrideRequest Enter “Y” to map existing mac address to a different profile. Enter “N” or blank to add the Mac Addresses
String N
3.1.3 Request Header
Please refer Request Headers.
3.1.4 Response Attributes
Name Value Place Holder Format Description
statusCode statusCode SUCCESS Give the status of request processing if it succeeded or
failed. The status will be SUCCESS if all macaddresses
are mapped .The status will be PARTIAL SUCCESS if we are
11/17/2017 RC PROVISIONING API SPEC
12
PARTIALSUCCESS able to map at least one map macaddress and at least one mac address is not mapped.
FAILURE
statusMessage statusMessage MACADDRESS MAPPED Macaddress is successfully mapped to a profile.
NO VALID MACADDRESS FOR MAPPING
There are no valid macadresses to map to a profile. Check “macStatusList” for details.
INVALID PROFILE NAME Entered profile name is invalid.
INVALID SETUP Entered sold to, ship to, pid combination is Invalid.
FAILED TO MAP MACADDRESS
Failed to map macaddress due to internal error. Please try again or open a case with Support.
INVALID USER User does not have access to Mac address management screen.
macStatusList
Returns the status of each individual macaddress.
Status <limit 1000 characters>
VALID It is a valid Macaddress and can be mapped to a profile.
INVALID Invalid Macaddress format.
MULTIPLE PID PRESENT
When customer is submitting mac addresses belonging to 2 different PIDS which belong to them. In a request, customer
can submit only the Macs associated to one PID.
MAC ADDRESS NOT AVAILABLE
Macaddress is already mapped to an existing profile of a
different user or is associated to the sales order of a different
organization.
VALID AVAILABLE Mac address has existing profile mapped to logged in
user.
pid <data> Gives the pid associated to the macaddress. If value is ‘NOT AVAILABLE’ then pid is not
available in the system.
11/17/2017 RC PROVISIONING API SPEC
13
errMsg INVALID FORMAT Macaddress is in invalid format. It should be 12 hexadecimal character.
Macaddress belong to multiple pid
Uploaded set of macaddress associated to different PIDs.
This MAC Address does not belong to you.
Macaddress is already mapped to an existing profile of a
different user or is associated to the sales order of a different
organization.
NA No Errors
profileName <data> Gives the profile name associated to the macaddress.
If value is ‘NOT AVAILABLE’ then macaddress is not
mapped to any profile in the system.
macAddr <data> Macaddress uploaded.
3.1.5 Response Body {
“statusCode”: “<statusCode>”,”statusMessage”:”<statusMessage>”, "macStatusList":[{"status":"<macaddressStatus>","pid":"<pid>","errMsg":"<errorMessage>","profileName":"<profileName>","macAddr":"<macaddress>"},{"status":"<macaddressStatus>","pid":"<pid>","errMsg":"<errorMessa
ge>","profileName":"<profileName>","macAddr":"< macAddress>"}] }
3.1.6 Sample Response Body //Success Response
{ “statusCode”: “SUCCESS”,”statusMessage”:”MAC ADDRESS MAPPED”, "macStatusList":[{"status":"VALID","pid":"SPA122-RC","errMsg":"","profileName":"test-
profile","macAddr":"105F4965E10E"},{"status":"VALID","pid":"SPA122-RC","errMsg":"","profileName":"test-profile","macAddr":"8E4D2D890CD8"},{"status":"VALID","pid":"SPA122-RC","errMsg":"","profileName":"test-profile","macAddr":"B2CEDB5DEE72"},{"status":"VALID","pid":"SPA122-RC","errMsg":"","profileName":"test-profile","macAddr":"105F4965E096"},{"status":"VALID","pid":"SPA122-RC","errMsg":"","profileName":"test-
profile","macAddr":"BAC7E70ECA4B"}]
}
11/17/2017 RC PROVISIONING API SPEC
14
11/17/2017 RC PROVISIONING API SPEC
15
3.2 Retrieve Profile
This service will be used to retrieve the profile names associated with the MAC addresses.
3.2.1 Request URI
POST https://apx.cisco.com/cdasvcs/api/rc/v1/fetchProfile
POST {"macAddress":["105F4965E096”,”105F4965E10E”,”BAC7E70ECA4B”,”8E4D2D890CD8”,”B2CEDB5DEE7"]}
3.2.2 Query Parameters
Name Description Format Mandatory(Y/N)
macAddress Mac for which profile needs to be obtained
List
Y
3.2.3 Request Header
Please refer Request Headers.
3.2.4 Response Attributes Name Value Place Holder Format Description
statusCode statusCode SUCCESS Give the status of request processing if it succeeded or
failed. FAILURE
statusMessage statusMessage INVALID USER User does not have access to Mac address management
screen.
macStatusList
Returns the status of each individual macaddress
uploaded.
status <limit 1000 characters>
VALID It is a valid Macaddress and can be mapped to a profile.
INVALID Invalid Macaddress format.
MAC ADDRESS NOT AVAILABLE
Macaddress is already mapped to an existing profile of a
different user or is associated to the sales order of a different
organization.
11/17/2017 RC PROVISIONING API SPEC
16
errMsg INVALID FORMAT Macaddress is in invalid format. It should be 12 hexadecimal character.
This Mac address does not belong to you.
Macaddress is already mapped to an existing profile of a
different user or is associated to the sales order of a different
organization.
NA No Errors
profileName <data> Gives the profile name associated to the macaddress.
If value is ‘NOT AVAILABLE’ then macaddress is not
mapped to any profile in the system.
macAddr <data> Macaddress uploaded.
3.2.5 Response Body {“statusCode”:”<statusCode>”,statusMessage":"<statusMessage>","macStatusList":[{"status":"<macaddressStatus>","errMsg":"<errorMessage>","profileName":"<profileName>","macAddr":"<macaddress>"},{"status":"<macaddressStatus>”,”errMsg":"<errorMessage>","profileName":"<profileName>","macAddr":"< macAddress>"}]
}
3.2.6 Sample Response Body //Success Response
{ “statusCode”:”SUCCESS”,"macStatusList":[{"status":"VALID","errMsg":"NA","profileName":"test-profile","macAddr":"105F4965E10E"},{"status":"VALID","errMsg":"NA","profileName":"test-profile","macAddr":"8E4D2D890CD8"},{"status":"VALID”,"errMsg":"","profileName":"test-
profile","macAddr":"B2CEDB5DEE72"},{"status":"VALID,"errMsg":"NA","profileName":"test-profile","macAddr":"105F4965E096"},{"status":"VALID”,"errMsg":"","profileName":"test-
profile","macAddr":"BAC7E70ECA4B"}]
}
//Failure Response
{"statusCode":"FAILURE","statusMessage":"INVALID USER"}
11/17/2017 RC PROVISIONING API SPEC
17
3.3 Disassociate MAC from a profile This service will be used to disassociate the macaddresses from the profile.
3.3.1 Request URI
POST https://apx.cisco.com/cdasvcs/api/rc/v1/disconnectMac
POST {"macAddress":["105F4965E096”,”105F4965E10E”,”BAC7E70ECA4B”,”8E4D2D890CD8”,”B2CEDB5DEE7"]}
3.3.2 Query Parameters
Name Description Format Mandatory(Y/N)
macAddress Mac which needs to be disassociated from the
profile
List
Y
3.3.3 Request Header
Please refer Request Headers.
3.3.4 Response Attributes
Name Value Place Holder Format Description
statusCode statusCode SUCCESS Give the status of request processing if it succeeded or
failed. The status will be SUCCESS if all macaddresses are disassociated .The status
will be PARTIAL SUCCESS if we are able to disassociate at least
one map macaddress and at least one mac address is not
disassociated.
PARTIALSUCCESS
FAILURE
statusMessage statusMessage INVALID USER User does not have access to Mac address management
screen.
NO VALID MACADDRESS FOR DISASSOCIATING
There are no valid macaddress for disassociating.
MACADDRESS DISASSOCIATED
Mac Address has been disassociated.
11/17/2017 RC PROVISIONING API SPEC
18
FAILED TO DISASSOCIATE MACADDRESS
Failed to disassociate mac address due to any error.
macStatusList
Returns the status of each individual macaddress
uploaded.
status <limit 1000 characters>
VALID It is a valid Macaddress and can be disassociated.
INVALID Invalid Macaddress format.
MAC ADDRESS NOT AVAILABLE
Macaddress is new and not available or already mapped to
an existing profile of a different user or is associated
to the sales order of a different organization.
errMsg INVALID FORMAT Macaddress is in invalid format. It should be 12 hexadecimal character.
This Mac address does not belong to you.
Macaddress is new and not available or already mapped to
an existing profile of a different user or is associated
to the sales order of a different organization.
NA No Errors
macAddr <data> Macaddress uploaded.
3.3.5 Response Body {“statusCode”:”<statusCode>”,”statusMessage":"<statusMessage>","macStatusList":[{"status":"<macaddressStatus>","errMsg":"<errorMessage>","macAddr":"<macaddress>"},{"status":"<macaddressStatus>”,”errMsg":"<errorMessage>","macAddr":"< macAddress>"}]
}
3.3.6 Sample Response Body //Success Response
{“statusCode”:”SUCCESS”,”statusMessage”:” MACADDRESS
DISASSOCIATED”,"macStatusList":[{"status":"VALID","errMsg":"NA","macAddr":"105F4965E10E"},{"status":"VALID","errMsg":"NA","macAddr":"8E4D2D890CD8"}}
//Failure Response
{"statusCode":"FAILURE","statusMessage":"INVALID USER"}
11/17/2017 RC PROVISIONING API SPEC
19
3.4 Get Devices for a Profile This service will be used to get a list of devices using the profile.
3.4.1 Request URI
POST https://apx.cisco.com/cdasvcs/api/rc/v1/getMacs
POST {"profileName": "test-profile","rowFrom":5, "rowTo":10}
3.4.2 Query Parameters
Name Description Format Mandatory(Y/N)
profileName Profile Name for which device list is required
String
Y
rowFrom The record from which data needs to be fetched.If input value is not given it will take rowFrom as 1.
int N
rowTo The record to which data needs to be fetched.If
input value is not given it will be set to
rowFrom+4999 by default.
int N
3.4.3 Request Header
Please refer Request Headers.
3.4.4 Response Attributes
Name Value Place Holder Format Description
statusCode statusCode SUCCESS The status will be SUCCESS if macaddress is fetched .The
status will be FAILURE in case device list is not fetched due to
errors.
FAILURE
statusMessage statusMessage INVALID USER User does not have access to Mac address management
screen.
INVALID PROFILE NAME Entered profile name is invalid.
11/17/2017 RC PROVISIONING API SPEC
20
NO DEVICES MAPPED TO THE PROFILE
There are no macaddress associated to the profile and
user.
DEVICE LIST FETCHED List of macaddress associated to the profile is fetched.
deviceCount deviceCount <data> Count of macaddress accosiate to the profile and user.
macActivationStatusList
Returns the list of macaddress and activation status.
macAddr <data> Macaddress associated to the profile.
status ACTIVE Device is activated.
INACTIVE Device is not activated.
activationDate <data> Date on which device was activate. Will be “NA” if device
is not activated.
3.4.1 Response Body {“statusCode”:”<statusCode>”,”statusMessage":"<statusMessage>", “deviceCount”:<deviceCount>,“macActivationStatusList":[{"status":"<activationStatus>",”activationDate”:”<activationDate>”,"macAddr":"<macaddress>"},{"status":"<activationStatus>”,”activationDate”:”<activationDate>”,”macAddr":"< macAddress>"}] }
3.4.1 Sample Response Body //Success Response
{"statusCode":"SUCCESS","statusMessage":"DEVICE LIST FETCHED","macActivationStatusList":[{"status":"ACTIVE","activationDate":"11/08/2016 11:34:10.965809 AM","macAddr":"AC7E8A59A122"},{"status":"ACTIVE","activationDate":"10/31/2016 07:09:06.376282 AM","macAddr":"AC7E8A59AEEA"},{"status":"ACTIVE","activationDate":"11/08/2016 12:47:42.839884 PM","macAddr":"AC7E8A59AD18"},{"status":"ACTIVE","activationDate":"11/01/2016 06:56:13.252189 AM","macAddr":"AC7E8A59AFA4"},{"status":"ACTIVE","activationDate":"08/25/2016 07:51:13.208035 AM","macAddr":"547C6946B542"},{"status":"ACTIVE","activationDate":"08/24/2016 12:58:14.443813 PM","macAddr":"547C6946B55C"}],"deviceCount":73874}
//Failure Response
{"statusCode":"FAILURE","statusMessage":"INVALID PROFILE NAME","deviceCount":0}
11/17/2017 RC PROVISIONING API SPEC
21
4 Appendix
4.1 Request Headers
Name Value Description Format
Authorization Bearer <token> It is the access token generated after client
authentication
Required.
It should be in the format of
“Bearer” followed by
token
Content-Type: application/json Content type
4.2 Error codes:
Message Message Code Entity
Error connecting to server. Please contact administrator
Service failure
Profiles not available If PID contains zero profile while
overriding
4.3 Generic Exceptions:
Http Status Code Message Description
<Not Authorized>
If token has expired
. Each token has a
validity of 3599
secs.
500 {
"status": "FAILED",
"messageCode": "RCProvisioning-GENERIC-
ERR-500",
"message": "Error Processing Your Request,
please try later",
"data": null
When service is
down
11/17/2017 RC PROVISIONING API SPEC
22
}
405 {
"status": "FAILED",
"messageCode": "RCProvisioning-GENERIC-
ERR-405",
"message": "Method not allowed",
"data": null
}
When resource is
not supporting the
http request
method
415 {
"status": "FAILED",
"messageCode": "RCProvisioning-GENERIC-
ERR-415",
"message": "Unsupported media type",
"data": null
}
When media type is
not supported
406 {
"status": "FAILED",
"messageCode": "RCProvisioning-GENERIC-
ERR-406",
"message": "Not acceptable",
"data": null
}
When response
type is not
matching with
header request
accept type
400 {
"status": "FAILED",
"messageCode": "RCProvisioning-GENERIC-
ERR-400",
"message": "Bad request",
"data": null
}
When request is
not meeting the
input criteria
404 {
"status": "FAILED",
"messageCode": "RCProvisioning-GENERIC-
ERR-404",
"message": "Resource not found",
When URL is not
correct
11/17/2017 RC PROVISIONING API SPEC
23
"data": null
}