2.4Comparing API styles

Saying "use an API" hides that design styles are not uniform. REST, which names resources as nouns, and RPC, which names operations as verbs (functions), change how you read URLs and methods. And synchronous (wait for the result on the spot) versus asynchronous (merely accept and get the result later) make the client entirely different to build. This section builds the ability to judge, from the API response in front of you (e.g., 202 Accepted) or the requirement (processing takes minutes), which style to design/use.

2.4.1REST and RPC

• REST is resource-oriented. The URL names a "thing" (a resource) and the operation on it is expressed by the HTTP method, e.g., GET /devices/42 (retrieve), DELETE /devices/42 (delete). It is stateless (each request is self-contained and the server keeps no state from prior calls), and its strength is riding cleanly on standard HTTP mechanisms (methods, statuses, caching).
• RPC (Remote Procedure Call) is procedure-oriented. The URL or message names a "function call," typically over a single POST sending a verb (operation name) + arguments such as {"method":"rebootDevice","params":{"id":42}}. gRPC and JSON-RPC are examples. It suits complex operations that do not fit "CRUD on a resource" but that you want to invoke as one action.
• How to tell: if the URL is noun (resource)-centric with the method as the operation it leans REST (GET /users/5); if the URL or body is verb (function name)-centric it leans RPC (POST /getUser {"id":5}). Exams ask "which style is this call?" or "designed RESTfully, what would the URL/method be?"

2.4.2Synchronous and asynchronous

• Synchronous means that after sending a request you wait on the spot until processing finishes and the result returns. It is simple to implement and suits quick retrievals like GET. But if processing takes long, the client is blocked meanwhile and risks a connection timeout.
• Asynchronous means the server merely accepts the request, immediately returns 202 Accepted, and does the real work in the background. The client later polls the job status (GET /jobs/{id}) or gets a completion notice via webhook/callback. It suits work that cannot block or be waited on—minutes-long bulk jobs, heavy aggregation, mass operations across many devices.

Suppose you consume, from a client, an API that "applies a config change to 1000 network devices at once." You try calling POST /config/apply synchronously; processing takes minutes, and after waiting for the response the client's HTTP connection times out and you receive no result. Thinking "just raise the timeout and stay synchronous" is a poor call—proxies and load balancers along the path have their own timeouts, so a long synchronous call is inherently fragile. Reading the docs, this endpoint is asynchronous: calling it immediately returns 202 Accepted with a body {"jobId":"abc123","status":"pending"}, and job completion is checked separately via GET /jobs/abc123. So the correct usage is: (1) submit with POST and receive 202 plus the jobId, then (2) poll GET /jobs/abc123 at a reasonable interval (with exponential backoff to respect rate limits) until status becomes completed/failed, or receive a completion notice via webhook if available. This design lets the client avoid holding a connection open through long processing. On style, this operation is less "CRUD on a resource" than "a procedure to apply en masse," carrying an RPC flavor, yet many Cisco platform APIs express asynchrony within REST by modeling the job as a resource (/jobs/{id}). The lesson: choose the style (REST/RPC) and call model (synchronous/asynchronous) from the processing time and requirement—synchronous REST for short, immediate answers; asynchronous (202 + job polling/callback) for long, bulk, or non-blocking work—and "endure it synchronously by raising the timeout" is not the sound approach.

2.4.3Section summary

• REST is resource (noun URL) + HTTP method and stateless; RPC is procedure-centric (verb, function call). Tell them apart by whether the URL is a noun or a verb
• Synchronous waits until the result returns (short retrievals); asynchronous accepts with 202 Accepted and fetches the result later via polling/callback (long/bulk work)
• For long processing, do not raise the timeout synchronously—design it as asynchronous + job polling/webhook