Understanding REST APIs and REST API Authentication

1. Start with a Familiar Browser Request

You already use HTTP every time you open a website. A REST API uses the same request-and-response foundation, but its audience is usually software rather than a person reading a page.

When browser JavaScript calls an API on another origin, the browser also evaluates CORS response headers. Use the CORS Tester to compare the endpoint's OPTIONS preflight and actual GET policy without supplying tokens or executing state-changing methods.

2. Read One API Request from Start to Finish

Suppose you want to check a loopback interface. Read the request as a short sentence: “Using my token, get the JSON representation of Loopback0 from this controller.”

GET /api/v1/interfaces/loopback0 HTTP/1.1
Host: 192.168.1.1:55443
Accept: application/json
Authorization: Bearer <access-token>

1. Method: GET says you want to read data without changing the resource.
2. Path: /api/v1/interfaces/loopback0 identifies the resource.
3. Accept header: the client asks the server to return JSON.
4. Authorization header: the bearer token proves the request has access.
5. Server response: a status code explains the outcome and the body carries the data or error details.

A successful response could look like this:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "name": "Loopback0",
  "admin_status": "up",
  "oper_status": "up",
  "ipv4_address": "10.10.10.1/32"
}

3. Match the Resource with the Right HTTP Method

A REST resource is a thing the API exposes. In networking, that could be an interface, VLAN, fabric site, policy, host, alarm, or device. Its URL identifies the object; the HTTP method describes what you want to do with it.

4. Let the Status Code Guide Your Next Step

When an API call fails, do not start by guessing at the JSON. Read the HTTP status code first. It narrows the problem to the request, authentication, permissions, missing resource, rate limit, or server.

5. Recognize What Makes an API RESTful

For daily network automation, you do not need to memorize every theory detail before sending your first request. Still, the REST constraints explain why API calls feel predictable.

1. Client-server. The client starts requests; the server answers them.
2. Stateless. Each request carries enough information for the server to process it.
3. Cacheable. Responses can indicate whether clients may reuse data instead of requesting it again.
4. Uniform interface. Resources are identified consistently, usually through URLs and standard representations.
5. Layered system. Load balancers, proxies or gateways can sit between client and server.
6. Code on demand. Optional; a server can send executable code, though API responses are usually static JSON or XML.

6. Choose an Authentication Method Deliberately

An API may expose inventory, topology, policy, and configuration actions. Authentication proves which person, script, or application is making the request before the server returns data or accepts a change.

7. Understand JSON Web Tokens in Plain Language

A JSON Web Token, or JWT, is a compact token with three dot-separated parts: header, payload and signature. The payload can include claims such as issuer, subject, issued-at time and expiration time.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

The token is convenient because the client can send it with each request. The risk is also obvious: if someone steals a valid token, they may be able to use the access it grants. That is why expiration, scopes, TLS and careful storage matter.

8. Build Safer API Automation

• Prefer scoped tokens or keys over broad administrator credentials.
• Plan for token expiration instead of assuming one token lasts forever.
• Respect rate limits and retry only when the operation is safe to repeat.
• Audit API access and investigate unusual failures or request volume.

9. Check Your Understanding

You send GET /api/v1/devices/42 with an expired bearer token and receive 401 Unauthorized. What should you conclude?

11. Frequently Asked Questions