Module 4: Understanding and

Using APIs

DevNet Associate v1.0

Module Objectives
Module Title: Understanding and Using APIs

Module Objective: Create REST API requests over HTTPS to securely integrate services.

Topic Title Topic Objective

Introducing APIs Explain the use of APIs.
API Design Styles Compare synchronous and asynchronous API design styles.
Introduction to REST APIs Explain the functions of REST APIs.
Authenticating a REST API Create REST API requests over HTTPS to securely integrate services.
Troubleshooting API calls Explain how to troubleshoot REST APIs

© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 2
4.1 Introducing APIs

© 2016 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 3
Understanding and Using APIs
What is an API?
• An Application Programming
Interface (API) allows one piece of
software talk to another.
Example of different types of API integrations
• It uses common web-based
interactions or communication
protocols and its own proprietary
standards.
• An API determines what type of
data, services, and functionality
the application exposes to third
parties.
• By providing APIs, applications
can control what they expose in a
secure way.
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 4
Understanding and Using APIs
Why use APIs?
• APIs are built to be consumed programmatically by other applications, and they can also be
used by humans who want to interact with the application manually.

Use cases of APIs are as follows:

• Automation tasks – Build a script that performs manual tasks automatically and
programmatically.
• Data integration – An application can consume or react to data provided by another
application.
• Functionality – An application can integrate another application's functionality into its
product.

© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 5
Understanding and Using APIs
APIs in Network & Security Use Case: Network Automation

• Network devices expose APIs for Traditional Approach:

automation.
▪ Manual CLI configuration
▪ APIs replace manual CLI
configuration ▪ Time-consuming and error-prone

▪ Enable scalable and programmable Using APIs:

networks ▪ Automate repetitive tasks
• Examples: ▪ Configure multiple devices at once
• Configure router/switches
▪ Reduce human error
• Retrieve interface status
Example:
• Monitor network traffic
• Manage firewall rules ▪ Python script configures 100 routers via
API
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 6
4.2 API Design Styles

© 2016 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 7
API Design Styles
Synchronous APIs
• Synchronous APIs respond to a request directly by
Synchronous APIs
providing data immediately.
When are APIs synchronous?
• APIs are synchronous when the data for the
request is readily available.
Benefits of a synchronous API design
• Synchronous APIs enable the application to
receive data immediately. If the API is designed
correctly, the application performance will be
better.
Client side processing
• The application that is making the API request Tickets are sold in first-come, first
must wait for the response before performing any served order. This is a synchronous
additional code execution tasks. process.
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 8
API Design Styles
Asynchronous APIs
• Asynchronous APIs provide a response (with no data) to
signify that the request has been received.
When are APIs asynchronous?
• APIs are asynchronous when the request takes some
Asynchronous APIs
time for the server to process or if data isn’t readily
available.
Benefit of asynchronous API design
• Asynchronous APIs allow the application to continue
execution without being blocked till the server processes
the request, thus resulting in better performance.
Client-side processing
• With asynchronous processing, the design of the API on
the server side defines the requirement on the client
side.
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 9
4.4 Introduction to REST APIs

© 2016 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 10
Introduction to REST APIs
REST Web Service APIs
• A REST Web service API (REST
API) is a programming interface
that communicates over HTTP.
REST API request/response model
• REST APIs use the same
concepts as the HTTP protocol
which are as follows:
• HTTP requests/responses

• HTTP verbs

• HTTP status codes

• HTTP headers/body

© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 11
REST APIs in Network Devices
Modern network devices expose REST APIs for programmability and automation

Where REST APIs are Used

Why REST APIs in Networking?
▪ SDN Controllers (e.g., Cisco DNA Center)
▪ Replace manual CLI configuration
→ Centralized network management and
automation ▪ Enable scalable automation

▪ Firewalls / Security Appliances ▪ Support integration with scripts and tools

→ Automate rule creation, policy updates (Python, Ansible)
▪ Cloud Networking Platforms Shift from device-by-device CLI →
→ Manage virtual networks, load balancers, centralized programmable control
security groups

© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 12
REST APIs in Network Devices

© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 13
Introduction to REST APIs
REST API Requests
• REST API requests are HTTP requests that are a way for an application (client) to ask the
server to perform a function.

• REST API requests are made up of four major components:

• Uniform Resource Identifier (URI)

• HTTP Method

• Header

• Body

© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 14
Introduction to REST APIs
REST API Requests (Contd.)
The Uniform Resource Identifier (URI), also referred to as Uniform Resource Locator (URL),
identifies which resource the client wants to manipulate. The components of a URI are:
• Scheme: specifies which HTTP protocol should be used, http or https.

• Authority: consists of two parts, namely, host and port.

• Path: represents the location of the resource, the data or object, to be manipulated on the
server.
• Query: provides additional details for scope, filtering, or to clarify a request.

Different components of a URI

© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 15
Introduction to REST APIs
REST API Requests (Contd.)
HTTP method:
• REST APIs use the standard HTTP methods to communicate to the web services for which
action is being requested for the given resource.
• The suggested mapping of the HTTP Method to the action is as follows:

HTTP Method Action Description

POST Create Create a new object or resource.
GET Read Retrieve resource details from the system.
PUT Update Replace or update an existing resource.
PATCH Partial Update Update some details from an existing resource.
DELETE Delete Remove a resource from the system.

© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 16
Introduction to REST APIs
REST API Requests (Contd.)
Header:
• HTTP headers are formatted as name-value pairs that are separated by a colon ( : ),
[name]:[value].

Two types of headers:

• Request headers - Include additional information that does not relate to the content of the
message.
Key Example Value Description
Authorization Basic dmFncmFudDp2YWdyYW Provide credentials to authorize the request

• Entity headers - Additional information that describes the content of the body of the message.
Key Example Value Description
Content-Type application/ json Specify the format of the data in the body

© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 17
Introduction to REST APIs
REST API Requests (Contd.)
Body:

• The body of the REST API request contains the data pertaining to the resource that the client
wants to manipulate.

• REST API requests that use the HTTP method POST, PUT, and PATCH typically include a
body.

• The body is optional depending on the HTTP method.

• If the data is provided in the body, then the data type must be specified in the header using
the Content-Type key.

© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 18
What Happens on the Network
▪ REST API communication occurs over TCP/IP using
HTTP/HTTPS

▪ Each API request is encapsulated as an HTTP message

▪ Travels from client → network → server → response back

Example HTTP Request:
Transport Layer:

▪ TCP ensures reliable delivery

▪ Port 80 (HTTP) / 443 (HTTPS)

Application Layer (HTTP):

▪ Request line + headers + optional body

API = Application layer, but depends on network stack

© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 19
Introduction to REST APIs
REST API Responses
• REST API responses are HTTP responses that communicate the results of a client's HTTP
request.

• REST API Responses are made up of three major components:

• HTTP Status

• Header

• Body

© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 20
Introduction to REST APIs
REST API Responses (Contd.)
HTTP Status
• The HTTP status code help the client determine the reason for the error and can sometimes
provide suggestions for fixing the problem.
• HTTP status codes consists of three digits, where the first digit is the response category and
the other two digits are assigned in numerical order.
• There are five different categories of HTTP status codes:
• 1xx – Informational – for informational purposes, responses do not contain a body
• 2xx – Success – the server received and accepted the request
• 3xx – Redirection – the client has an additional action to take to get the request completed
• 4xx -- Client Error – the request contains an error such as bad syntax or invalid input
• 5xx -- Server Error – unable to fulfill the valid requests.

© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 21
Introduction to REST APIs
REST API Responses (Contd.)
The common HTTP status codes are as follows:
HTTP Status Code Status Message Description
200 Ok Request was successfully and typically contains a payload (body)
400 Bad Request Request will not be processed due to an error with the request
Request does not have valid authentication credentials to perform
401 Unauthorized
the request
403 Forbidden Request was understood but has been rejected by the server
Request cannot be fulfilled because the resource path of the
404 Not Found
request was not found on the server
500 Internal Server Error Request cannot be fulfilled due to a server error

© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 22
401 vs 403 –Security Perspective

Code Meaning Cause

401 Unauthorized Invalid or missing credentials

Valid credentials but

403 Forbidden
insufficient permissions

Flow Understanding: Example:

▪ Client sends request ▪ No token / wrong password → 401

▪ Server checks authentication ▪ Valid login but no access rights → 403

▪ Server checks authorization Important in troubleshooting access

control issues

© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 23
Why HTTPS is Critical
Why HTTPS is Critical in API Risks without HTTPS:
Communication
▪ Credential interception (sniffing)
▪ HTTP transmits data in plaintext
▪ Token/session hijacking
▪ HTTPS uses TLS encryption to secure
communication ▪ Man-in-the-Middle (MITM) attacks

Security Protections: In network environments, unencrypted

API = security vulnerability
▪ Confidentiality → Data cannot be read

▪ Integrity → Data cannot be modified

▪ Authentication → Server identity verified

© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 24
4.5 Authenticating to a REST API

© 2016 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 25
Authenticating to a REST API
REST API Authentication
• REST APIs require authentication so that random users cannot access, create, update, or
delete information incorrectly or maliciously.

• Some APIs that do not require authentication are read-only and they do not contain any
critical or confidential information.

© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 26
Authenticating to a REST API
Authentication Vs. Authorization
Authentication:
• Authentication proves the user’s identity.

• For example, when you go to the airport, you have to

show your government-issued identification or use
biometrics to prove that you are the person you claim to
be.

Authorization:
• Authorization defines the user access.

• It is the act where the user is proving to have permissions

to perform the requested action on that resource.
• For example, when you go to a concert, all you need to
show is your ticket to prove that you are allowed in.
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 27
Authenticating to a REST API
Authentication mechanisms
The common types of authentication mechanisms include:
• Basic authentication: It transmits credentials as username/password pairs separated with
a colon (:) and encoded using Base64.
• Bearer authentication: It uses a bearer token, which is a string generated by an
authentication server such as an Identity Service (IdS).
• API Key: It is a unique alphanumeric string generated by the server and assigned to a
user. The two types of API keys are public and private.

Authorization Mechanisms
• Open Authorization (Oauth) combines authentication with authorization.

• Oauth = secure way to get a token for access,/

© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 28
Security Considerations in API Authentication
▪ Basic Authentication ▪ Bearer Tokens
• Base64 encoding ≠ encryption • Must be protected (can be reused if
• Vulnerable if not using HTTPS stolen)

▪ API Keys ▪ Best Practices:

• Should not be exposed in URL or • Always use HTTPS

client-side code • Apply least privilege access
• Must be stored securely • Rotate credentials periodically

Security depends on implementation, not method alone

© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 29
Common API Security Threats
▪ Credential Sniffing ▪ API Abuse / Rate Attacks
• Occurs over unencrypted HTTP • Excessive requests causing service
disruption
▪ Token Theft
▪ Unauthorized Access
• Stolen tokens allow unauthorized
access • Improper authorization checks
▪ Broken Authentication APIs expand attack surface in modern
networks
• Weak validation or improper session
handling

© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 30
Authenticating to a REST API
Lab - Explore REST APIs with API Simulator and Postman
In this lab, you will complete the following objectives:
• Part 1: Launch the DEVASC VM

• Part 2: Explore API Documentation Using the API Simulator

• Part 3: Use Postman to Make API Calls to the API Simulator

• Part 4: Use Python to Add 100 Books to the API Simulator

© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 31
4.8 Troubleshooting API Calls

© 2016 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 32
Troubleshooting API Calls
Network-Level Troubleshooting for APIs
Layered Approach: Tools:
▪ 1. Network Layer ▪ curl → quick testing

▪ Check connectivity (ping) ▪ Postman → structured testing

▪ Verify routing ▪ Wireshark → packet inspection

▪ 2. Transport Layer Troubleshooting APIs = network +

application analysis
▪ Check open ports (80 / 443)

▪ Firewall filtering

▪ 3. Application Layer

▪ Inspect HTTP request/response

▪ Validate headers and payload

© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 33
Troubleshooting API Calls
Troubleshooting REST API Requests
• There will be instances where you will make an API request but will not get the expected
response. Hence, learning to troubleshoot the most common REST API issues is important.

• Always have the API reference guide and API authentication information handy while
troubleshooting the REST API issues.

© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 34
Troubleshooting API Calls
Interpreting Status Codes
• The status code is a part of HTTP/1.1 standard (RFC 7231), where the first digit defines the
class of the response and the last two digits do not have any class or categorization role.
• The five categories of status codes are as follows:
• 1xx: Informational - Request received, continuing to process.
• 2xx: Success - The action was successfully received, understood, and accepted.
• 3xx: Redirection - Further action must be taken in order to complete the request.
• 4xx: Client Error - The request contains bad syntax or cannot be fulfilled.
• 5xx: Server Error - The server failed to fulfill an apparently valid request.
• Steps to troubleshoot errors:
• Check the return code - It can help to output the return code in the script during the
development phase.
• Check the response body - Output the response body during development
• Use status code reference – If the issues cannot be resolved by checking the return
code and response body.
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 35
Troubleshooting API Calls
2xx and 4xx Status Codes
• 2xx – Success error: Successfully received, understood and accepted

• 4xx – Client-side error: Error is on the client side.

Troubleshooting common 4xx errors:

400 – Bad request
The request could not be understood by the server due to malformed syntax, which is mainly due to:
• Misspelling of resources
• Syntax issue in JSON object.

© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 36
Troubleshooting API Calls
2xx and 4xx Status Codes (Contd.)
Example : This example returns a status code of 400.

The server side also tells you "No id field provided", because the id is mandatory for this API
request.

© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 37
Troubleshooting API Calls
2xx and 4xx Status Codes (Contd.)
401 – Unauthorized:
• This error message means the server could not authenticate the request.
• Check your credentials, including username, password, API key, token, request URI
Example

The authentication auth=("person1","great") should be added in the code

© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 38
Troubleshooting API Calls
2xx and 4xx Status Codes (Contd.)
403 – Forbidden
• The server recognizes the authentication credentials, but the client is not authorized to
perform the request.
• Example: The status code 403 is not an authentication issue; it is just that the user does not have
enough privileges to use that particular API.

The authentication should be modified to use person2/super instead of person1/great.

© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 39