REST APIs, Authentication, HTTP Methods and CRUD
An API is how one program uses another's data and functions. Many REST APIs use HTTP, because HTTP already works the REST way: client and server, stateless, cacheable. Programs do four things to data, CRUD: create with POST, read with GET, update with PUT or PATCH, and delete with DELETE. Each request names its resource with a URI.
By Arif, founder of Daveth · Updated
The full 9 min walkthrough is in Daveth Pro (Network). See what the plan opens
What this page answers
What is a REST API?
An application programming interface that follows REST's rules, client and server, stateless and cacheable, usually over HTTP. A program sends a verb and a URI, and the server acts on that resource and replies. Read it in “Asking a program, not a screen”
Which HTTP verbs match CRUD?
Create is POST, read is GET, update is PUT or PATCH, and delete is DELETE. Read it in “REST over HTTP: verbs and CRUD”
Asking a program, not a screen
Month ten. The controller in Ravi's plan (10.3) offers everything it does through its northbound API, not only its GUI. Before trusting that, Ravi tries a lab controller that has one, with a read-only token, against one port on the lab switch: Gi0/2, the port to the lab router.
An API (application programming interface) is how one program uses another's data and functions: reading its variables, changing them, creating new ones, deleting them. It lets programs cooperate, whether they run on one computer or on different computers across a network; an API used across a network has to say which protocols it uses, and often that's HTTP. Developers add APIs so that other software can use what theirs does, and much of modern programming is learning other people's APIs. One kind is especially popular in network automation: REST (REpresentational State Transfer).
REST has six defining attributes: client/server architecture, stateless operation, a clear statement of what is cacheable, a uniform interface, layering, and code-on-demand. The first three do most of the work.
Client/server. A program that offers a REST API acts as the REST server, and any program that calls it is a REST client. The client sends a request, the server's API code decides how to answer, and the reply carries the data back.
Stateless. The server doesn't use the history of earlier requests to process a new one; each request stands on its own. (TCP, which carries sequence numbers from one segment to the next, is stateful; UDP is stateless.) Stateless doesn't mean the server remembers nothing: it still holds its data, and every request must still carry what the server needs, credentials included.
Cacheable, or not. Every resource must be clearly marked as cacheable or not, with a time frame when it is, so a client can reuse what rarely changes, like a logo on every page of a website, and ask again for what does, like the results of a search. The point is performance: fewer fetches. A port's live status is the second kind.
The app uses the service counter, not a tiny robot clicking through the dashboard.
REST over HTTP: verbs and CRUD
REST doesn't require HTTP, but many REST APIs use it, because HTTP already works the REST way: client and server, stateless, headers that mark what may be cached, and verbs that say what a request wants done. Programs do four things to data, remembered as CRUD: create, read, update, delete.
| Action | CRUD | HTTP verb |
|---|---|---|
| create new data structures and variables at the server | Create | POST |
| read (retrieve) variable names, structures and values | Read | GET |
| update or replace the values of some variables | Update | PATCH, PUT |
| delete some variables and data structures | Delete | DELETE |
Update: PATCH or PUT. Where an API has both, PUT usually replaces the whole resource with what the request sends, and PATCH changes only the parts it names. The match isn't exact, though: depending on the API, POST, PATCH and PUT can each be used to create or to update. The API's documentation says which verbs each resource supports, and it matters. CRUD's D is not an instruction to press DELETE: first ask whether the resource supports removal at all, and what removing it would affect.
Naming the resource: URIs
Every request carries a verb and a URI (uniform resource identifier) in its header, inside HTTP, inside TCP and IP. (On the wire, the request line carries the path and a Host header carries the hostname.) Clicking a link in a web browser sends exactly this kind of request, a GET, and the reply is the page's text and images. The API's creator gives each resource its own URI and documents them all, and the programmer writing the client reads that documentation to build requests.
| Part | Here | What it does |
|---|---|---|
| protocol | https | HTTP secured with SSL encryption (today, its successor TLS) |
| hostname or address | ctrl1.lab.example | the REST server; a name is resolved to an IP address first |
| path (the resource) | /api/v1/devices/labsw1/interfaces/Gi0-2 | which resource, as the API's documentation defines it |
| query (parameters) | ?fields=description | optional: after a "?", narrows what the resource returns |
The path. The protocol says how (HTTPS: HTTP secured with SSL, today TLS), the hostname or IP address says which server (a name is resolved to an address first), the path says which resource, and anything after a "?" is a query that narrows the answer. Credentials belong in none of those parts: REST APIs carry authentication in HTTP header fields.
Continue the lesson
The whole lesson, with its drawings and its questions. 3 more sections after the ones above.

