What's changed: Initial version
6.3REST APIs and data formats
Covers, from a practical angle, the nature of REST APIs (stateless, running over HTTP) that underpin operating controllers and devices from automation; the correspondence between CRUD operations and HTTP methods (POST/GET/PUT/DELETE); the HTTP status codes (200/201/4xx/5xx) that indicate success or failure; and reading JSON (the {} object, [] array, keys and values, and data types)—the main vehicle of data exchange.
The entry point for "operating the controller from a script" in the previous section is the REST API. A REST API reuses the very HTTP mechanism we use in browsers every day, to "read (GET)," "create (POST)," "update (PUT)," and "delete (DELETE)" device state. Most of the data exchanged is in JSON, a lightweight format. This section builds the basic etiquette of REST APIs and the ability to correctly read returned JSON, from the practical viewpoint of operating via API instead of CLI.
6.3.1REST API nature and CRUD/HTTP methods
- A REST API is an API style that points at resources (devices, configs, state) by URL over HTTP and operates on them with HTTP methods. It is stateless: the server retains no client session state between requests, so each request is self-contained, carrying the needed information (auth token, etc.) each time.
- CRUD (Create/Read/Update/Delete) maps to HTTP methods: Create=POST / Read=GET / Update=PUT (partial update=PATCH) / Delete=DELETE. Example:
GET /api/v1/interfacesreads the state of all interfaces;POST /api/v1/vlanscreates a new VLAN. - A request carries headers (
Content-Type: application/json, an auth token, etc.), and for create/update a body (a JSON payload). A GET usually has no body and identifies the target via the URL.
Continue reading — free sign-up
You're reading the free preview. Sign up free to read this section in full, plus every chapter (including 4+) and all questions.