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.

In Daveth Pro (Network)9 min video · lab: First API call

By , founder of Daveth · Updated

Opening frame of the video walkthrough of REST APIs, Authentication, HTTP Methods and CRUD

Watch this lesson

9 min · Video walkthrough

In Daveth Pro (Network)

The full 9 min walkthrough is in Daveth Pro (Network). See what the plan opens

Upcoming practical lab

Lab N23: First API call

What the lab covers

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.

ActionCRUDHTTP verb
create new data structures and variables at the serverCreatePOST
read (retrieve) variable names, structures and valuesReadGET
update or replace the values of some variablesUpdatePATCH, PUT
delete some variables and data structuresDeleteDELETE

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.

PartHereWhat it does
protocolhttpsHTTP secured with SSL encryption (today, its successor TLS)
hostname or addressctrl1.lab.examplethe REST server; a name is resolved to an IP address first
path (the resource)/api/v1/devices/labsw1/interfaces/Gi0-2which resource, as the API's documentation defines it
query (parameters)?fields=descriptionoptional: 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.