Understanding and Using APIs

Introduction

APIs (Application Programming Interfaces) are the building blocks of modern network automation — they allow software, scripts, and tools to communicate with network devices and cloud platforms programmatically instead of through a CLI. For the DEVASC exam, you need to understand how REST APIs work, how to interact with them using HTTP methods, and how to interpret and construct requests and responses. In real-world IT work, nearly every modern platform — from Cisco DNA Center to Webex to Meraki — exposes an API, so this knowledge is immediately practical.

Key Concepts

API (Application Programming Interface): An API is a defined contract that lets one piece of software talk to another. Think of it as a menu at a restaurant — it tells you exactly what you can order and what format to use, without needing to know how the kitchen works.

REST (Representational State Transfer): REST is the most common style of API used in networking and cloud platforms. It uses standard HTTP methods and treats everything on the server as a "resource" that you can read, create, update, or delete using a URL.

HTTP Methods (Verbs): REST APIs use HTTP methods to express intent — GET retrieves data, POST creates something new, PUT replaces an existing resource, PATCH partially updates it, and DELETE removes it. Choosing the wrong method is the most common beginner mistake.

Endpoint / URI: The endpoint is the specific URL you send your request to, identifying which resource you want to interact with. For example, https://api.meraki.com/api/v1/organizations points to the organizations resource on the Meraki API.

Request and Response: Every API interaction has two sides — the request (what you send, including method, URL, headers, and optional body) and the response (what the server sends back, including a status code, headers, and usually a JSON body).

JSON (JavaScript Object Notation): JSON is the dominant data format used in REST API bodies. It represents data as key-value pairs and nested structures, and it is both human-readable and easy for code to parse.

Authentication: APIs require proof of identity before they respond. Common methods include API keys (a token passed in a header), OAuth 2.0 (a delegated token system), and Basic Authentication (username/password encoded in Base64). Most Cisco platform APIs use token-based auth.

Headers: HTTP headers are metadata attached to a request or response. In API work, the most important are Content-Type (tells the server what format the body is in, usually application/json) and Authorization (carries your credentials or token).

Status Codes: The server's response always includes a three-digit HTTP status code telling you whether the request succeeded or why it failed. These are grouped into classes: 2xx = success, 4xx = client error, 5xx = server error.

Rate Limiting: Many APIs limit how many requests you can make in a given time window to prevent overload. When you exceed the limit, the server typically returns a 429 Too Many Requests status code.

How It Works

1. Identify the endpoint. Read the API documentation to find the correct URL for the resource you want (e.g., get a list of devices, create a new webhook).

2. Authenticate. Obtain your credentials. For token-based APIs (like Cisco DNA Center), you first make a POST request to an authentication endpoint with your username and password, and the server returns a token. You include this token in subsequent requests.

3. Build the request. Choose the correct HTTP method. Set the required headers — at minimum Content-Type: application/json and your Authorization header. If creating or updating data, write a JSON body.

4. Send the request. Using a tool like Postman or Python's requests library, send the HTTP request to the endpoint.

5. Read the response. Check the status code first — a 200 OK or 201 Created means success. Then parse the JSON body to extract the data you need.

6. Handle errors. If you receive a 4xx code, the problem is on your side (bad URL, missing auth, malformed JSON). If you receive a 5xx code, the problem is on the server's side. Your code should handle both gracefully.

Commands / Syntax / Key Values

Python requests library — common patterns:

import requests

# GET request
response = requests.get(url, headers=headers)

# POST request with JSON body
response = requests.post(url, headers=headers, json=payload)

# Access status code
print(response.status_code)

# Parse JSON response body
data = response.json()

Common HTTP Status Codes:

Key Headers:

Cisco DNA Center Auth endpoint (for reference):

POST https://<dnac-ip>/dna/system/api/v1/auth/token

Headers: Authorization: Basic <base64-encoded user:pass>

⚠ Exam Traps

Trap 1 — Confusing 401 and 403: Students often treat these as interchangeable. They are not. 401 Unauthorized means the request has no valid credentials or the token is missing/expired — the server does not know who you are. 403 Forbidden means the server knows exactly who you are, but your account does not have permission to do what you asked. The fix for 401 is to authenticate; the fix for 403 is to change your permission level.

Trap 2 — Using POST when you should use PUT or PATCH: POST creates a new resource. PUT replaces an entire existing resource. PATCH updates only specific fields of an existing resource. Exam questions often describe a scenario where you want to update one field in an existing object — the correct answer is PATCH, not POST, even though beginners tend to reach for POST whenever they are "sending data."

Trap 3 — Assuming GET requests can have a body: Technically HTTP does not forbid a body on a GET request, but REST convention and most real-world APIs ignore or reject it. On the exam, if you need to send data to filter or create something, that is a signal to use POST, not GET with a body.

Trap 4 — Mixing up Content-Type and Accept: Content-Type describes what you are sending in the request body. Accept describes what format you want the server to send back. A question might describe a scenario where the server returns XML instead of JSON and ask what header controls this — the answer is Accept, not Content-Type.

Trap 5 — Thinking Base64 encoding is encryption: When you authenticate with Basic Auth, the username and password are Base64-encoded, not encrypted. Base64 can be decoded by anyone who intercepts it. Exam questions may ask whether Basic Auth provides security — the answer is: only if you are using it over HTTPS. Base64 alone provides zero confidentiality.

Practice Questions

Q1. A developer sends a REST API request and receives a 403 status code. What is the most likely cause? - A. The request body contains invalid JSON - B. The authentication token has expired - C. The authenticated user does not have permission to access the resource - D. The API endpoint URL is incorrect

Answer: C — A 403 Forbidden response means the server recognized the requester's identity but denied access due to insufficient permissions; an expired token would produce a 401.

Q2. A script needs to update only the description field of an existing network device object via a REST API. Which HTTP method is most appropriate? - A. POST - B. GET - C. PUT - D. PATCH