2 Network APIs and Data Models

What network APIs do

Network APIs let software inspect and change network resources, including interfaces, routes, VLANs, and device settings, without manually entering commands on each device. A client sends a request to a device or controller; the service processes it and returns a response. HTTP-based APIs are common, while network-management protocols such as gNMI provide operations designed for configuration and telemetry.

Models and data formats

A data model defines which information exists, how it is organized, its data types, and constraints on valid values. For example, an interface model might define a name, an enabled flag, and a numeric MTU. Models help clients and devices interpret the same fields consistently.

YANG is a language for defining hierarchical network-management models. OpenConfig publishes vendor-neutral YANG models for common configuration and operational data. A model is a schema, not the same thing as the format used to encode data on the wire.

Common data formats

• JSON is a widely used text format for API requests and responses. It is composed of objects, arrays, strings, numbers, booleans, and null values; its usual media type is application/json.

• XML is a structured text format still used by some network-management APIs and protocols.

• Protocol Buffers is a schema-based binary format often used with gRPC, including gNMI.

• YAML is often used for human-edited configuration files, but it is not automatically the format accepted by an API.

Check API documentation for supported formats, model versions, required fields, and whether a value represents configured intent or observed operational state.

HTTP requests and responses

An HTTP request includes a method, a target URL, headers, and sometimes a body. The method expresses the operation: GET retrieves data, POST commonly creates a resource or starts an operation, PUT replaces a resource, and PATCH applies a partial change when the API supports it. Exact behavior is defined by the API.

An HTTP response includes a status code, headers, and often a body. The status-code classes are 2xx success, 3xx redirection, 4xx client-side error, and 5xx server-side error.

Making and checking HTTP calls

Use a deliberate workflow for API operations:

1. Read the API documentation to identify the base URL, endpoint, method, data model, and required headers.

2. Authenticate using an approved mechanism and send the request over HTTPS.

3. Inspect the status code and response body, and validate that returned data matches the expected model.

4. For a change, verify the resulting device or controller state. An accepted request does not by itself prove that the intended network outcome has been achieved.

The following example uses a fictional endpoint; real paths and methods vary by product. Supply the token securely rather than committing it to source code or placing it in a URL.

A successful response might contain a JSON representation such as:

To change the resource, an API might accept a PUT with a JSON body. Confirm the endpoint’s update semantics before using PUT; it may replace the complete resource rather than update just one field.

The server might return 200 OK with a representation of the updated resource, or 204 No Content with no body. A 400 or 422 can indicate invalid input; 401 indicates missing or invalid authentication; 403 indicates insufficient permission; and 404 indicates that the target was not found. Inspect the response and, where practical, make a follow-up read to confirm the change.

Authentication and safe automation

An API may use a username and password, an API key, an OAuth access token, or client certificates. With bearer-token authentication, the client typically sends Authorization: Bearer <token>. Anyone possessing a bearer token can use it, so protect it by using HTTPS with certificate validation, keeping credentials out of logs and code repositories, and granting only the permissions needed.

Automation should account for failures and differences between devices. Check API capabilities and supported models before deploying a change; validate input; handle timeouts, rate limits, and error responses; and make retries carefully. A repeated PUT is intended to have the same effect as one successful PUT, but a repeated POST may create duplicate operations or resources. Use change controls and verify operational state after configuration updates.

Network management with gNMI

gNMI is a gRPC-based network-management interface. Its remote procedure calls include:

• Capabilities to discover supported models and encodings.

• Get to retrieve a snapshot.

• Set to modify data.

• Subscribe to receive updates.

Subscriptions can provide a one-time result, polling, or a continuing stream, making them useful for telemetry. As with HTTP APIs, clients should confirm which paths, models, encodings, and authorization rules the target supports.

Putting the pieces together

Network APIs exchange structured requests and responses. Data models define the meaning and constraints of fields, while formats such as JSON or Protocol Buffers encode those fields for transport. Reliable API workflows consult the API contract, authenticate securely, send the intended operation, interpret the response, and verify the resulting network state.