What is a REST API
A REST API is a resource-oriented interface style for managing systems over HTTP. Every capability is designed around resources — things such as interfaces, VLANs, routes, or policies — and each resource is located with a URI. Operations on those resources are then described using standard HTTP methods: GET, POST, PUT, PATCH, and DELETE.
In a network device context, a REST API gives software a structured, programmatic way to read and change device configuration and status, without going through the command line. That makes it a foundation for network automation: orchestration systems, management platforms, and custom scripts can all drive a switch with ordinary HTTPS requests and JSON data, instead of scripting CLI sessions and parsing text output.
How a REST API Works
Resources and collections. The REST model organizes everything as resources. Resources can be grouped into collections: each collection is homogeneous, meaning it contains only one type of resource, and it is unordered. A resource can also stand alone outside any collection, in which case it is called a singleton resource. A collection is itself a resource — it can sit at the top level of the API, or live inside a single resource as a subset, which is typically used to express a "contained" relationship.
Requests. A request is addressed to a URL such as https://SWITCH_IP/rest/v1/interfaces, where SWITCH_IP is the device's IP address. Query parameters, introduced by ?, assigned with =, and joined by &, refine what comes back. Two keywords are especially useful: selector filters individual attribute values of the resources returned, and depth controls how many levels of sub-resources are resolved, up to 10 levels.
HTTP methods. The data format for both requests and responses is JSON, and each method has a clearly defined role:
GET retrieves a resource. It is read-only, changes no state, has no side effects, and should not carry a request body; any extra information goes in query parameters. Unless stated otherwise, it returns the configured state.
POST creates a new resource. Every POST must include a JSON body describing the resource, and a successful response returns a 201 code with a Location header holding the full URL of the new resource, for use in later requests.
PUT replaces an existing resource, and its body must contain the complete representation of the resource's mandatory attributes. It cannot be used to create a resource.
PATCH updates an existing resource with new information. Like PUT, it modifies something that already exists and cannot create one.
DELETE removes a resource and should not carry a request body. Deleting something already deleted returns a 404 Not Found.
Responses. The HTTP status code tells the client whether the request worked. A 200 means a successful GET, 201 means a resource was created, 202 means the request was accepted into a backend queue as an asynchronous task, and 204 means a successful delete or modification with no content to return. Client-side problems return codes such as 400 (invalid request), 401 (not authorized, for example incorrect credentials), 403 (authorized but access is forbidden), 404 (record not found), 406 (requested format unavailable), 410 (resource permanently gone), and 422 (a validation error when creating an object), while 500 signals a server error.
The response body is also in a unified JSON format. A GET returns query results directly, while create, update, and delete operations return a structure containing status_code, result, module, and, for sub-resource operations, resource. On success, result is the string "OK"; on failure, it carries the reason. Batch operations return a top-level status_code — 200 if everything succeeded, 207 if only some operations succeeded, and 400 if all failed — plus a results array reporting each individual operation's outcome.
Documentation and data model. The API's data model is described using YANG, and the reference documentation shows it as tree diagrams in which each node is marked as read-write (rw) configuration data or read-only (ro) status data. Property tables label each field as parameter (P), mandatory (M), optional (O), conditionally mandatory (CM), conditionally optional (CO), or read-only (RO), and describe valid values with regular expressions, numeric ranges, enumerations, or plain language. Two path conventions keep URLs short: path compression omits a list node from the URL and data when it is the only subnode in its container and the container's name is a prefix or plural of the list's name, and path omission means case nodes never need to appear in a URL or body — only the relevant child nodes do.
Why a REST API is Beneficial
Makes automation straightforward: Standard HTTP and JSON are supported by virtually every programming language and tool, so integrating a switch into scripts, pipelines, and orchestration systems does not require a specialized client.
Consistent and predictable: One resource model, one set of methods, and one response format apply across features, so what a developer learns for one part of the API carries over to the rest.
Clear feedback on every call: Well-defined return codes distinguish success, client errors, and server errors, and batch responses report per-operation results, making failures easy to detect and handle in code.
Efficient for bulk changes: Batch operations let a client apply many changes in a single request and still see exactly which succeeded and which did not.
Precise, lightweight reads:
selectoranddepthlet a client request only the attributes and levels of detail it needs, rather than pulling entire configurations.Structured data instead of text: Configuration and status come back as JSON objects rather than CLI text that must be parsed, which reduces fragility when software versions change.