21.3 REST

Introduction

REST is a style of designing web APIs that is heavily used in network automation. When a network device, controller, or cloud platform says it has a "REST API," it usually means you can control it using standard HTTP methods, readable URLs, and structured data such as JSON. In this chapter you will focus on what is specific to REST as an architectural style and how that affects the way you interact with networked systems through APIs.

REST as an Architectural Style

REST stands for "Representational State Transfer." It is not a protocol, a product, or a standard, but a set of design principles for building web services. These principles describe how clients and servers should interact using HTTP so that systems stay simple, scalable, and loosely coupled.

In networking, REST is important because most modern controllers, firewalls, switches, routers, SDN systems, and cloud platforms expose RESTful APIs. This allows automation tools and scripts to use a consistent pattern when making requests, even if the underlying devices are very different.

A RESTful system focuses on resources rather than actions. A resource can be a user, an interface, a VLAN, a route, or a configuration object. The client manipulates these resources through their representations, usually JSON, over HTTP operations.

Resources and URIs

The central idea in REST is the resource. Each resource is identified by a URI, often called an endpoint when you speak about APIs. You do not send commands such as "create-vlan" or "set-interface-up" encoded in custom messages. Instead, you address resources with predictable paths and apply standard HTTP methods to them.

For example, a network controller might expose switch interfaces as resources. You could see URIs like:

• /api/v1/devices
• /api/v1/devices/1234
• /api/v1/devices/1234/interfaces
• /api/v1/devices/1234/interfaces/Gi0/1

Each URI represents a resource or a collection of resources. In REST, URIs should be nouns and should describe the resource itself, not the action you want to perform. Actions are expressed by the HTTP method you choose.

Many REST APIs in networking use versioning in the path, such as /api/v1/, to allow changes in future versions without breaking existing clients.

HTTP Methods and CRUD

REST builds on the standard HTTP methods and maps them to common data operations. You will frequently see the CRUD pattern, which stands for Create, Read, Update, Delete. Each of these actions is represented by a specific HTTP method when applied to a URI.

Typical mappings are:

In a network context, a GET request to /api/v1/vlans might return a list of all VLANs. A POST to /api/v1/vlans with a JSON body might create a new VLAN. A PUT to /api/v1/vlans/10 might replace the definition of VLAN 10. A DELETE to /api/v1/vlans/10 would remove VLAN 10.

Different vendors sometimes interpret PUT and PATCH slightly differently. Some use PUT for partial updates, others use PATCH. You always need to check the vendor documentation, but the general concept of using HTTP methods for CRUD remains the same.

Representations and Content Types

REST speaks about "representations" of resources instead of the resources themselves. A resource is the abstract thing, such as "interface Gi0/1 on device 1234." Its representation is the concrete format you receive or send over the network, such as a JSON document.

The same resource can have multiple possible representations. For example, some APIs let you choose between JSON and XML. The content type, indicated by the HTTP header Content-Type, tells the server what format you are sending. The Accept header tells the server what format you would like to receive.

For network automation, JSON has become the dominant representation format. An example GET response for an interface resource could look like this in JSON:

{
  "name": "GigabitEthernet0/1",
  "description": "Uplink to core",
  "enabled": true,
  "mtu": 1500
}

When you want to modify or create a resource, your HTTP request body contains a similar JSON representation. The server stores or applies this representation to the underlying system.

REST benefits from standardized content types. Some common ones you will see are:

Statelessness and Client Server Separation

REST has a strict requirement that interactions between client and server are stateless. Each HTTP request must contain all the information the server needs to understand and process it. The server should not rely on stored session state between requests.

In practice this means that authentication tokens, parameters, and instructions must travel with each request. For example, in a network automation tool, every API call might include an authorization header containing a token. The server reads the token and decides whether it should allow the operation, but it does not remember previous requests as a session.

This stateless property simplifies scaling and reliability because the server does not need to track per client session data. Load balancers can send any request to any available replica. For automation, it also makes error handling simpler. If a script fails halfway, it can often repeat individual operations without worrying about restoring session state.

REST also separates client and server concerns. The client is responsible for the user interface or automation logic. The server is responsible for providing the resources over HTTP and for enforcing rules. As long as the REST API contract stays stable, clients and servers can evolve independently.

HTTP Status Codes and Error Handling

REST APIs rely heavily on HTTP status codes to communicate success and failure. You do not parse human language error messages to decide what happened. Instead, you read the numeric status code and act accordingly.

Common status code categories are:

Network focused APIs often use specific codes such as:

Error responses usually also include a JSON body that describes the problem in more detail, such as an error code or a helpful message. Automation scripts can use both the HTTP status and the error body to decide whether to retry, to stop, or to adjust the request.

Query Parameters and Filtering

REST APIs often use query parameters to filter, sort, or paginate collections of resources. These parameters appear after a question mark in the URI. They do not change the resource identity itself, but they modify how the server returns representations.

Examples include:

• /api/v1/devices?site=Paris
• /api/v1/interfaces?device_id=1234&status=down
• /api/v1/logs?limit=100&offset=200

In network APIs, query parameters are especially useful when dealing with large environments. Instead of fetching every device and then filtering in your code, you let the REST service perform the filtering, which reduces bandwidth, processing time, and memory usage.

Some APIs also use query parameters to control which fields are returned, such as only the name and status of interfaces. This is commonly called "field selection" and helps keep responses small.

REST and Caching

REST was designed with caching in mind. HTTP supports many headers that control cache behavior. Caching lets clients or intermediaries reuse responses to avoid repeating expensive operations.

For static or rarely changing resources, such as a list of supported models or static documentation, the server can allow caching. For highly dynamic data, such as interface counters or real time events, caching is usually disabled. In many network automation tasks, fresh data is more important than caching, but understanding that caching exists is still useful.

Common caching related headers include:

In some cases, clients use ETags to perform conditional GET or conditional updates. This allows a client to say "only return this if it has changed" or "only apply this update if the resource is still in this version." That can help prevent overwriting someone else's changes.

Hypermedia and REST Maturity Levels

REST as originally defined includes the idea of hypermedia as the engine of application state, often abbreviated HATEOAS. In practice, this means responses contain links to related resources so the client can discover how to navigate the API.

For example, a device resource might include a _links section:

{
  "id": "1234",
  "hostname": "sw-core-1",
  "_links": {
    "self": { "href": "/api/v1/devices/1234" },
    "interfaces": { "href": "/api/v1/devices/1234/interfaces" }
  }
}

Many network APIs do not fully implement hypermedia. They may provide documentation outside the API and expect clients to know the URI structure in advance. REST has different "maturity levels" that describe how closely a particular API follows REST principles. Some APIs use HTTP as a simple transport with one or two endpoints, while others use fully defined resources, HTTP methods, proper status codes, and hypermedia links.

Understanding that not all "REST APIs" are equally RESTful helps set expectations. When working with different vendors, you often see a range from basic JSON over HTTP to well designed resource oriented APIs.

REST vs RPC Style APIs

REST is one way to design APIs. Another style is RPC, which stands for Remote Procedure Call. RPC based APIs treat remote calls like function calls or commands. URIs often contain verbs, such as /api/v1/add_vlan or /api/v1/set_interface_admin_state.

REST in contrast tries to use nouns in URIs and uses HTTP methods to express the action. For example, instead of POST /api/v1/add_vlan, a RESTful design would use POST /api/v1/vlans with a body that describes the VLAN.

Many network devices supported older RPC style APIs before they adopted REST. Some platforms still provide both, for example a REST interface and a gRPC or SOAP interface. For automation, REST is usually simpler to use from scripting languages, because it builds directly on HTTP and JSON.

Idempotence and Safe Operations

REST gives special attention to two properties of operations, safety and idempotence.

A safe method is one that does not change server state. In REST, a GET request is supposed to be safe. You can call it as many times as you like without changing the underlying resources. This is important for monitoring tools and for debugging, because they often repeat GET requests.

An idempotent method is one where applying the same request multiple times has the same effect as applying it once. For example, PUT and DELETE are defined to be idempotent. If you DELETE /api/v1/vlans/10 repeatedly, the first request removes the resource and the next ones leave the system in the same state, with VLAN 10 still absent.

POST is not idempotent, because sending the same POST twice often creates two separate resources. This matters in network automation when your code needs to retry after failures. If a POST times out, you must decide whether the resource may already exist and handle that carefully. With idempotent methods, retries are usually safer.

REST in Network Automation Workflows

In network automation, REST is usually consumed by scripts or tools rather than by web browsers. The client prepares HTTP requests with the correct URI, method, headers, and JSON body, sends them to the REST API endpoint, then parses the JSON response and HTTP status code.

Typical automation workflows include:

• Discovering devices by calling a controller's /devices resource.
• Reading interface status by using GET on /interfaces or a device specific URI.
• Applying configuration changes using PUT or PATCH on /config resources.
• Creating new objects such as VLANs, VRFs, or policies using POST on collection URIs.
• Deleting obsolete objects using DELETE on the correct resource URIs.

Because REST is based on HTTP, you can often test individual calls with generic tools such as curl or Postman before you automate them in code. This makes it easier to debug problems and to explore APIs.

REST is also the foundation that many automation libraries and frameworks build upon. For example, when configuration management tools interact with a network controller, they usually call REST endpoints in the background. Understanding REST helps you troubleshoot and customize those higher level tools.

Summary

REST provides a consistent, resource oriented way to interact with networked systems using HTTP. It organizes interactions around URIs that represent resources, uses HTTP methods to map to CRUD operations, and relies on representations such as JSON to carry data. REST is stateless, uses HTTP status codes to report results, and often uses query parameters for filtering and pagination. These properties make REST well suited for network automation, where scripts and tools need a predictable and machine friendly way to query and configure devices and controllers.