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://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=en"target="_blank">POSTMAN</a> is already installed. You can start it from the Google App Launcher or from Chrome by clicking <ahref="https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=en"target="_blank">here</a> and clicking on**Launch App**.
If you are on a DevNet Zone station, <ahref="https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=en"target="_blank">Postman</a> is already installed. You can start it from the Google App Launcher or Chrome by clicking <ahref="https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=en"target="_blank">here</a> and clicking **Launch App**.
16
15
17
-
- 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 own APIC-EM controller, you can use the Always-On APIC-EM Lab:
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:
18
17
*https://sandboxapicem.cisco.com
19
-
***username:** devnetuser
18
+
***username:** devnetuser
20
19
***password:** Cisco123!
21
20
22
21
## Step 1. Find the APIC-EM API Resources and Documentation
23
22
24
-
A good starting point to understand any API is to look at the documentation for the API. Let's 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 APIC-EM API.
25
24
26
25
1. In a browser, navigate to the <ahref="https://developer.cisco.com"target="_blank">DevNet</a> home page.
27
-
2. Click the **Login** link located on the top right of the web page.
26
+
2. Click the **Login** link located at the top right of the webpage.
If you want 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 web page and enter your credentials.
29
+
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.
31
30
<br/><br/>
32
31
4. Use the menu at the top to navigate to the APIC-EM web portal.
33
-
* Click the **Technologies** link to see the submenu.
34
-
* Click on **Networking**
35
-
* From the list of technologies, click on **APIC Enterprise Module (APIC-EM)**<br/>The APIC-EM web page appears.
32
+
* 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.
For this lab, we are going to use the <ahref="https://developer.cisco.com/site/apic-em/"target="_blank">APIC-EM APIs</a>.
24
+
For this lab, you are going to use the <ahref="https://developer.cisco.com/site/apic-em/"target="_blank">APIC-EM APIs</a>.
25
25
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>, allows the deployment and execution of application policy across your networking infrastructure.
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.
27
27
28
-
Using the APIC-EM APIs, we can retrieve information about devices on our network including a list of hosts, network devices, or users. We are going to use these features as examples to learn how to make REST calls from Python.
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.
29
29
30
-
Take a look at the <ahref="http://devnetapic.cisco.com/"target="_blank">APIC-EM Reference Docs</a> to see the details of all of the APIC-EM functions.
30
+
Look at the <ahref="http://devnetapic.cisco.com/"target="_blank">APIC-EM Reference Docs</a> to see the details of the APIC-EM functions.
31
31
32
32
33
33
### How does this work?
34
34
35
35
![](/posts/files/coding-101-rest-basics-ga/assets/images/howitworks.jpg"How it Works")
36
36
37
-
REST is centered around the HTTP request and response model. Consuming an API is just as simple as making an HTTP request.
37
+
REST is centered around the HTTP request and response model. Consuming an API is as simple as making an HTTP request.
38
38
39
-
In this example, we request the list of hosts, and that information is returned to us in the response. The data returned in the response is usually formatted as json or xml.
39
+
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
40
41
41
(<ahref="http://www.json.org/"target="_blank">JSON</a> -- JavaScript Object Notation, is a lightweight text-based open standard designed for human-readable data interchange.)
## Step 3. What do I need to know to make a Request?
2
2
3
-
To construct a request, you need to know the following information for the API that you are calling. You can find this information in the API reference documentation.
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
5
5
-**Method**
6
+
Choose one of the following http methods:
6
7
* GET - Retrieve data
7
8
* POST - Create something new
8
9
* PUT - Update data
9
10
* DELETE - Delete data
10
11
11
12
-**URL**
12
-
* The URL for the endpoint you want to call
13
+
* Determine the URL of the endpoint you want to call.
* Where `{APIC-EMController}` is the controller IP or hostname
15
-
* If you are not using your own APIC-EM controller, use the Always-On APIC-EM Lab: ![https://devnetapi.cisco.com/sandbox/apic_em]() .
15
+
* Where `{APIC-EMController}` is the controller IP or hostname.
16
+
* Use the Cisco DevNet Learning Lab's APIC-EM controller, at https://devnetapi.cisco.com/sandbox/apic_em, or enter the URL/IP address of an APIC-EM controller on your network.
16
17
-**URL Parameters**
17
-
*The parameters that you can pass as part of the URL.
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.
18
19
-**Authentication**
19
-
* You need to know the authentication type to use. Basic HTTP, token-based, and OAuth are common types.
20
-
* Authentication credentials
20
+
* Determine which authentication type to use. Basic HTTP, token-based, and OAuth are common types.
21
+
* Add the authentication credentials to the API call you are preparing.
21
22
-**Custom Headers**
22
-
* Does the API require you to send any HTTP Headers?
23
-
* Example: Content-Type: application/json
23
+
* If required, add any HTTP Headers to the API call you are preparing. For example: `Content-Type: application/json`.
24
24
-**Request Body**
25
-
* JSON or XML containing data that is needed to complete request can be sent in the body of the request
25
+
* If required, include a JSON- or XML-formatted request body that contains any data that is needed.
26
26
27
-
### A Little About Authentication
27
+
### About Authentication
28
28
29
-
There are three common types of authentication for REST APIs. Authentication is used to control access and access rights to the REST APIs. For example, some users might have read-only access which means that they can make only API endpoints that read data. Other users might be allowed to both read and change (add, edit, delete) data, meaning they can call any of the API endpoints. These access rights are typically-based upon assigned user roles such as *Administrator*, which grants a user full rights to change data, and *User*, which grants read-only access.
29
+
Authentication controls whether a user user can access a specific API endpoint and how they can it. For example, one user might have read-only privileges, which they can only make API calls that read data. Another user might have read and change (add, edit, delete) privileges to every endpoint, which means they can make any API call. These access rights are typically-based upon assigned user roles such as *Administrator*, which grants a user full rights to change data, and *User*, which grants read-only access.
30
30
31
-
1.**Basic HTTP:** The username and password are passed to the server in an encoded string. For more information, see [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication).
32
-
2.**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 is used to identify the user and rights when making API calls to verify access and control. See [OAuth](https://en.wikipedia.org/wiki/OAuth) for more information.
31
+
REST APIs have three common methods to authenticate users:
32
+
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
+
***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.
33
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.
34
36
35
-
APIC-EM uses token-based authentication. So the first request we 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 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.
36
38
37
39
The steps for using the APIC-EM authentication token are:
38
40
@@ -42,45 +44,40 @@ The steps for using the APIC-EM authentication token are:
42
44
43
45
### Using the API Reference Documentation
44
46
45
-
The API Reference Documentation is where you can find the list of all of the API methods and the details for how to make each request. When you are starting to work with a new API,
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,
46
48
the API Reference is one of the most important sources of information.
47
49
48
-
Let's take a look at the Ticket API in APIC-EM.
50
+
Study the Ticket API in APIC-EM:
49
51
50
-
* Open the <ahref="http://devnetapic.cisco.com/"target="_blank">APIC-EM Reference Docs</a> The entire API is presented in scrollable format.
52
+
* Open the <ahref="http://devnetapic.cisco.com/"target="_blank">APIC-EM Reference Docs</a>. The entire API is presented in scrollable format.
The API Reference includes information data attributes to be sent and returned. The returned data is defined in the Response portion which includes the HTTP status codes along with the data format and attributes to be returned.
63
+
* The API Reference includes attributes to be sent and returned. The Response portion defines the returned data, including HTTP status codes.
64
64
65
-
* HTTP Status Codes
66
-
* HTTP status codes are used to return success, error, or other statuses. [http://www.w3.org/Protocols/HTTP/HTRESP.html](http://www.w3.org/Protocols/HTTP/HTRESP.html)
67
-
* Some common examples are:
65
+
* HTTP status codes indicate success, error, or other conditions. For more information, see [http://www.w3.org/Protocols/HTTP/HTRESP.html](http://www.w3.org/Protocols/HTTP/HTRESP.html)
66
+
Some common codes are:
68
67
* 200 OK
69
68
* 202 Accepted/Processing
70
69
* 401 Not Authorized
71
70
72
71
73
-
* 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, we can see that the response string contains a "serviceTicket" attribute with a value of type string. This is the token value that is needed to make api calls for all of the other API endpoints.
72
+
* 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.
* 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://devnetapi.cisco.com/sandbox/apic_em`.
41
40
***Headers**
42
-
* For POST calls, specify the 'Content-Type' as 'application/json' in the header. It's typical to include this header with all REST method (GET, POST, PUT, DELETE …etc) calls.
41
+
* Specify the 'Content-Type' as 'application/json'. It's typical to include this header with all HTTP methods (GET, POST, PUT, DELETE) calls.
43
42
***Authentication**
44
43
* In this API call, the authentication data is passed in the body.
45
44
***Body**
46
-
* The username and password used to log into the APIC-EM Controller must be provided in JSON format in the body.
45
+
* Provide the username and password for logging into the APIC-EM Controller in JSON format.
0 commit comments