Understanding REST APIs: CRUD and HTTP Verbs

What is a REST API?

At its core, an Application Programming Interface (API) is a contract that allows two pieces of software to talk to each other. In network automation, this means a script or an application (the client) can programmatically interact with a network controller or device (the server).

While there are many types of APIs, the most prevalent style for web-based services and modern network controllers is REST, which stands for REpresentational State Transfer. REST isn't a strict protocol, but rather an architectural style—a set of principles for designing networked applications. An API that adheres to these principles is called a RESTful or REST-based API.

The following short video provides a great analogy, framing the API as the language used between a controller and the devices it manages.

The Language of REST: CRUD and HTTP Verbs

REST is built around the idea of resources. A resource is any object or piece of data that the server can provide. In a networking context, a resource could be:

• A specific interface on a router.
• The routing table of a switch.
• A list of all devices in the network.
• A security policy.

Each resource is accessible via a unique address called a URI (Uniform Resource Identifier).

With these resources, there are four basic actions you can perform. This set of actions is known as CRUD:

• Create: Make a new resource.
• Read: Retrieve a representation of a resource.
• Update: Modify an existing resource.
• Delete: Remove a resource.

Conveniently, REST APIs typically use the HTTP/S protocol for communication. As you know from your networking studies, HTTP already includes methods (or "verbs") that map directly to these CRUD operations.

Let's break down this mapping. The following video from Jeremy's IT Lab offers a clear and detailed explanation of CRUD and how these operations align with HTTP verbs.

To solidify this, let's review the mapping in a more formal way.

A Note on PUT vs. POST and PATCH

You'll notice that the "Update" operation can be handled by both PUT and PATCH. There is a key distinction:

• PUT is used to replace an entire resource with new data. If you only provide a subset of the resource's attributes, the others may be deleted or set to default values.
• PATCH is used for partial updates. You only send the specific attributes you want to change, and the rest of the resource remains untouched.

Another important concept is idempotency. An operation is idempotent if making the same request multiple times has the same effect as making it once.

• GET, PUT, and DELETE are idempotent. Getting the same resource 10 times is the same as getting it once. Replacing a resource with the same data 10 times is the same as doing it once.
• POST is not idempotent. Sending the same POST request multiple times will create multiple new resources.

This distinction is crucial for building reliable automation scripts.

The REST Request-Response Model

Now that we have the verbs (GET, POST, etc.) and the nouns (URIs identifying resources), we can form a complete request. The interaction is a simple client-server model.

A REST client sends an HTTP request that includes:

1. HTTP Verb: The action to perform (e.g., GET).
2. URI: The address of the resource.
3. HTTP Headers: Metadata, such as authentication tokens or the desired response format (Accept: application/json).
4. Request Body (optional): The data for the new resource, used with POST and PUT/PATCH.

The server sends an HTTP response that includes:

1. Status Code: A 3-digit code indicating success or failure (e.g., 200 OK, 404 Not Found).
2. HTTP Headers: Response metadata.
3. Response Body (optional): The requested data (for a GET) or status information.

Let's return to the Jeremy's IT Lab video to see this request-response cycle detailed, including the important status codes.

Key Architectural Characteristics

Finally, to be considered "RESTful," an API should adhere to a few key architectural constraints. While there are six official constraints, three are most relevant for your current studies:

1. Client-Server Architecture: The client (which makes requests) and the server (which holds the resources and responds) are separate. They evolve independently, connected only by the API contract. This separation of concerns is a fundamental design principle.
2. Stateless: This is a critical concept. Each request from a client to a server must contain all the information needed to understand and process the request. The server does not store any information about the client's session between requests. This makes the system more reliable, scalable, and easier to manage, as any server can handle any request. This contrasts with a stateful protocol like TCP, which maintains connection state.
3. Cacheable: Responses from the server should declare whether they can be cached by the client. Caching data that doesn't change frequently reduces the number of requests to the server, improving performance and efficiency.

Conclusion

In this lesson, we demystified the "language" of modern network automation APIs. You've learned how the REST architectural style provides a simple yet powerful framework for programs to interact with network resources.

Key Takeaways:

• REST is an architectural style for APIs, not a specific protocol. It's built on a client-server model and is stateless.
• REST operates on resources, each identified by a unique URI.
• The four fundamental operations are CRUD: Create, Read, Update, and Delete.
• REST APIs typically use HTTP/S, mapping CRUD operations to HTTP verbs: POST (Create), GET (Read), PUT/PATCH (Update), and DELETE (Delete).
• The client-server interaction follows a request-response model, with HTTP status codes indicating the outcome.

In our next lesson, we will build directly on this foundation. Now that we understand how to ask for things using REST and HTTP verbs, we need to look at the structure of the data we send and receive. We will be exploring JSON (JavaScript Object Notation), the lightweight, human-readable data format that has become the standard for REST APIs.