You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
If you are on a DevNet Zone station, <ahref="https://www.getpostman.com"target="_blank">Postman</a> is already installed. You can start it from the Google App Launcher or Chrome by clicking <ahref="https://www.getpostman.com"target="_blank">here</a> and clicking **Launch App**.
13
+
-[Postman](https://www.getpostman.com) installed.
14
+
If you are on a DevNet Zone station, Postman is already installed.
15
15
16
-
- Access to an APIC-EM Controller. To run the code samples, you need access to an APIC-EM controller. If you are not using your APIC-EM controller, you can use the APIC-EM Lab:
17
-
*https://sandboxapicem.cisco.com
16
+
- Access to DNA Center. To run the code samples, you need access to DNA Center. You can use the DNA Center DevNet Sandbox:
17
+
*https://sandboxdnac.cisco.com
18
18
***username:** devnetuser
19
19
***password:** Cisco123!
20
20
21
-
## Step 1. Find the APIC-EM API Resources and Documentation
21
+
## Step 1. Find the DNA Center API Resources and Documentation
22
22
23
-
A good starting point to understand any API is to look at the documentation for the API. Now, find documentation for the APIC-EM API.
23
+
A good starting point to understand any API is to look at the documentation for the API. Now, find documentation for the DNA Center API.
24
24
25
-
1. In a browser, navigate to the <ahref="https://developer.cisco.com"target="_blank">DevNet</a> home page.
26
-
2. Click the **Login** link located at the top right of the webpage.
To log in with a Cisco ID but do not have a Cisco Connection Online ID (CCO ID) click the **Register Now** button and follow the instructions. Then, return to the Log In webpage and enter your credentials.
30
-
<br/><br/>
31
-
4. Use the menu at the top to navigate to the APIC-EM web portal.
25
+
1. In a browser, navigate to the [DevNet](https://developer.cisco.com/) home page.
26
+
1. Use the menu at the top to navigate to the DNA Center Platform page.
32
27
* Click the **Technologies** link to see the submenu.
33
-
* Click **Networking**
34
-
* From the list of technologies, click **APIC Enterprise Module (APIC-EM)**<br/>The APIC-EM webpage appears.
28
+
* Click **Networking**.
29
+
* From the list of technologies, click **DNA Center Platform**.
@@ -10,25 +10,23 @@ There are two major types of web services – **REST** and **SOAP**.
10
10
REST is an architecture style for designing networked applications.
11
11
A REST web service is as easy to call as making an HTTP request.
12
12
RESTful interfaces usually offer the CRUD (Create, Read, Update, Delete) operations.
13
-
To know more about REST in general, this is a great <ahref="https://en.m.wikipedia.org/wiki/Representational_state_transfer"target="_blank">REST definition</a>.
14
-
13
+
To know more about REST in general, this is a great [REST definition](https://en.m.wikipedia.org/wiki/Representational_state_transfer).
For this lab, you are going to use the <ahref="https://developer.cisco.com/site/apic-em/"target="_blank">APIC-EM APIs</a>.
21
+
### DNA Center API is a REST API
25
22
26
-
The Application Policy Infrastructure Control (APIC) Enterprise Module (EM), Application Programming Interface (API), <ahref="https://developer.cisco.com/site/apic-em/"target="_blank">APIC-EM APIs</a>, enables deploying and running application policies across your networking infrastructure.
23
+
For this lab, you are going to use the [DNA Center APIs](https://developer.cisco.com/site/dna-center-rest-api/).
27
24
28
-
Using the APIC-EM APIs, you can retrieve information about devices on your network including a list of hosts, network devices, or users. You are going to use these features as examples to learn how to make REST calls from Python.
25
+
DNA Center APIs enable deploying and running application policies across your networking infrastructure.
29
26
30
-
Look at the <ahref="https://developer.cisco.com/site/apic-em-rest-api//"target="_blank">APIC-EM Reference Docs</a> to see the details of the APIC-EM functions.
27
+
Using the DNA Center APIs, you can retrieve information about devices on your network including a list of hosts, network devices, or users. You are going to use these features as examples to learn how to make REST calls from Python.
31
28
29
+
Look at the [DNA Center documentation](https://developer.cisco.com/site/dna-center-rest-api/) to see the details of the functions.
32
30
33
31
### How does this work?
34
32
@@ -38,8 +36,8 @@ REST is centered around the HTTP request and response model. Consuming an API is
38
36
39
37
In this example, you request the list of hosts, and that information is returned to you in the response. The data returned in the response is usually formatted as JSON or XML.
40
38
41
-
(<ahref="https://www.json.org/"target="_blank">JSON</a> -- JavaScript Object Notation, is a lightweight text-based open standard designed for human-readable data interchange.)
39
+
*[JSON](https://www.json.org/) - JSON, or JavaScript Object Notation, is a lightweight text-based open standard designed for human-readable data interchange.
42
40
43
-
(<ahref="https://www.w3schools.com/xml/xml_whatis.asp"target="_blank">XML</a> -- eXtensible Markup Language, a language designed to store and transport data.)
41
+
*[XML](https://www.w3schools.com/xml/xml_whatis.asp) - XML, or eXtensible Markup Language, a language designed to store and transport data.
## Step 3. What do I need to know to make a Request?
1
+
## Step 3: What do I need to know to make a request?
2
2
3
3
To construct a request, determine the following information for the API that you are calling. You can find this information in the API reference documentation.
4
4
@@ -11,9 +11,9 @@ Choose one of the following http methods:
11
11
12
12
-**URL**
13
13
* Determine the URL of the endpoint you want to call.
* Where `{APIC-EMController}` is the controller IP or hostname.
16
-
* Use the Cisco DevNet Learning Lab's APIC-EM controller, at https://sandboxapicem.cisco.com/, or enter the URL/IP address of an APIC-EM controller on your network.
* Where `sandboxdnac.cisco.com` is the controller IP or hostname.
16
+
* Use the Cisco DevNet Learning Lab's DNA Center, at https://sandboxdnac.cisco.com/, or enter the URL/IP address of an DNA Center on your network.
17
17
-**URL Parameters**
18
18
* If the endpoint requires URL parameters, pass them as part of the URL. To get this information, refer to the reference documentation for the particular endpoint.
19
19
-**Authentication**
@@ -32,31 +32,26 @@ REST APIs have three common methods to authenticate users:
32
32
33
33
***Basic HTTP:** The username and password are passed to the server as an encoded string. For more information, see [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication).
34
34
***OAuth:** Open standard for HTTP authentication and session management. Creates an access token associated with a specific user that also specifies the user rights. The token identifies the user and rights when making API calls to verify access and control. See [OAuth](https://en.wikipedia.org/wiki/OAuth) for more information.
35
-
3.**Token:** As with OAuth, a token is created and passed with each API call, but there is no session management and tracking of clients. This simplifies interaction between the server and client. APIC-EM uses this design for authentication management. See [Token Based Authentication](https://scotch.io/tutorials/the-ins-and-outs-of-token-based-authentication) for more information.
35
+
3.**Token:** As with OAuth, a token is created and passed with each API call, but there is no session management and tracking of clients. This simplifies interaction between the server and client. See [Token Based Authentication](https://scotch.io/tutorials/the-ins-and-outs-of-token-based-authentication) for more information.
36
36
37
-
APIC-EM uses token-based authentication. So the first request you need to make creates a token. In APIC-EM, this token is called a *service ticket*. The controller uses the service ticket to determine which endpoints you can access. The service ticket must be included in every API call except the one that creates the ticket.
37
+
APIC-EM uses token-based authentication. So the first request you need to make creates a token. In DNA Center, this string is called a *token*. The controller uses the token to determine which endpoints you can access. The token must be included in every API call.
38
38
39
-
The steps for using the APIC-EM authentication token are:
39
+
The steps for using the DNA Center authentication token are:
40
40
41
-
1.Create a ticket
41
+
1.Send a POST to the token endpoint.
42
42
2. A ticket (token) is returned in response body.
43
43
3. Include this token in the 'X-Auth-Token' header on all subsequent requests.
44
44
45
45
### Using the API Reference Documentation
46
46
47
-
The API Reference Documentation is where you can find the list of the API methods and the details for information on how to make each request. When you are starting to work with a new API,
48
-
the API Reference is one of the most important sources of information.
47
+
The API Reference Documentation is where you can find the list of the API methods and the details for information on how to make each request. When you are starting to work with a new API, the API Reference is one of the most important sources of information.
49
48
50
49
Study the Ticket API in APIC-EM:
51
50
52
-
* Open the <ahref="https://developer.cisco.com/site/apic-em/docs/api.html?version=1.6"target="_blank">APIC-EM Reference Docs</a>. Pick the proper version of API. The entire API is presented in scrollable format.
51
+
* Open the [DNA Center API reference docs](https://developer.cisco.com/site/dna-center-rest-api/). Pick the proper version of API. The entire API is presented in scrollable format.
* Click **Roll Based Access Control**, then scroll down to **ticket**.
57
-
58
-
* Click **'POST' /ticket**. This endpoint provides functionality to create a ticket.
59
-
60
55
* The API Reference includes attributes to be sent and returned. The Response portion defines the returned data, including HTTP status codes.
61
56
62
57
* HTTP status codes indicate success, error, or other conditions. For more information, see [https://www.w3.org/Protocols/HTTP/HTRESP.html](https://www.w3.org/Protocols/HTTP/HTRESP.html)
@@ -66,15 +61,12 @@ Study the Ticket API in APIC-EM:
66
61
* 401 Not Authorized
67
62
68
63
69
-
* Review the content to see what data is expected to be sent to the server and returned to your application. Both are circled here. In the example response for the Create Ticket request, you can see that the response string contains a `serviceTicket` attribute with a value of type string. This value is the authentication token you will need to make calls to all of the other API endpoints.
64
+
* Review the content to see what data is expected to be sent to the server and returned to your application. In the example response for the network devices request, you can see that the response string contains a `hostName` attribute with a value of type Array[string].
* In the Parameters section, click **Example Value**. Double-clicking the box moves the parameters to an editable box on the left to try out the function.
Now, look at how to use the API to create a service ticket for authentication.
5
+
Now, look at how to use the API to create a token for authentication.
6
6
7
-
You need to know how to construct the request to retrieve the service ticket. Use the API docs to determine the:
7
+
You need to know how to construct the request to retrieve the token. Use the API docs to determine the:
8
8
9
9
* Method
10
10
* URL
11
11
* Headers
12
12
* Authentication
13
13
* Body
14
14
15
-
All of the URLs for APIC-EM begin with:
15
+
Get the description of the token API call from the [DNA Center API Docs](https://developer.cisco.com/site/dna-center-rest-api/). Choose the proper API version.
16
16
17
-
```http
18
-
19
-
https://{APIC-EM-Server}/api/v1
17
+
`POST /api/v1/token`: This method creates a new user token.
20
18
19
+
The HTTP call to a create a token is easy.
21
20
```
22
21
23
-
Get the description of the ticket API call from the -- <ahref="https://developer.cisco.com/site/apic-em/docs/api.html?version=1.6"target="_blank">APIC-EM API Docs</a>. Choose the proper API version.
24
-
25
-
`POST /api/v1/ticket`: This method creates a new user ticket
26
-
27
-
28
-
The HTTP call to a create a service ticket is easy.
29
-
```http
30
-
31
-
https://{APIC-EM-Server}/api/v1/ticket
22
+
POST https://{DNA-Center-Server}/api/system/v1/auth/token
32
23
33
24
```
34
25
35
-
To get the service ticket your request will look like this:
26
+
To get the token your request will look like this:
* Substitute `{APIC-EM-Server}` with the IP address or hostname of the APIC-EM controller you are using. For example, the Cisco DevNet Learning Labs APIC-EM controller is `https://sandboxapicem.cisco.com/`.
* Substitute `{DNA-Center-Server}` with the IP address or hostname of the DNA Center you are using. For example, the Cisco DevNet Learning Labs DNA Center is `https://sandboxdnac.cisco.com/`.
40
31
***Headers**
41
32
* Specify the 'Content-Type' as 'application/json'. It's typical to include this header with all HTTP methods (GET, POST, PUT, DELETE) calls.
42
33
***Authentication**
43
34
* In this API call, the authentication data is passed in the body.
44
35
***Body**
45
-
* Provide the username and password for logging into the APIC-EM Controller in JSON format.
0 commit comments