REST vs RPC, Synchronous vs Asynchronous

Mental model

Cisco objective 2.8 says “Compare common API styles (REST, RPC, synchronous, and asynchronous)”. That is two different axes.

• Shape of the API — REST vs RPC. How you address the thing you want to act on, and how you pick the action.
• Timing of the answer — synchronous vs asynchronous. Does the answer come back in the same HTTP response, or later?

Any real API picks one from each axis. Most modern Cisco APIs are REST + synchronous for small operations, REST + async for anything that takes time (device deployment, bulk import, long reports).

REST vs RPC

REST (REpresentational State Transfer)

Everything is a resource with a URL. The HTTP method is the verb.

GET    /devices                → list devices
POST   /devices                → create a device
GET    /devices/42             → read device 42
PUT    /devices/42             → replace device 42
PATCH  /devices/42             → partially update device 42
DELETE /devices/42             → remove device 42

• Stateless: every request stands alone with its auth.
• Cache-friendly: GETs are cacheable; the URL alone identifies the resource.
• Dominant style for modern network APIs: Catalyst Center, Meraki, Webex all speak REST.

RPC (Remote Procedure Call)

The URL names a function, and the body carries the arguments.

POST /createDevice     body={"name":"sw3","ip":"10.0.0.3"}
POST /listClients      body={"deviceId":42}
POST /rebootSwitch     body={"deviceId":42,"delaySec":60}

• Feels like calling a function.
• gRPC and NX-API (legacy) and JSON-RPC flavors used in some vendor tools.
• gNMI (used for streaming telemetry) is on top of gRPC.
• Harder to cache (every call is a POST).

Side by side

Rule of thumb: if the API docs talk about “resources” and show URLs like /x/{id}/y, it is REST. If they talk about “methods” and show URLs like /doThing, it is RPC-ish.

Synchronous vs asynchronous

Synchronous

Client sends a request, server does the work, server returns the result. All in one HTTP round-trip.

POST /devices  body={"name":"sw3","ip":"10.0.0.3"}
→ 201 Created
   body={"id":42,"name":"sw3","ip":"10.0.0.3"}

Good for small, fast operations (< ~5 seconds). Easy to code.

Asynchronous

Server cannot answer within a few seconds (deploying 500 switches, generating a big report), so it accepts the request and gives you a way to check later.

Two patterns:

Polling:

POST /deployments   body={...large job...}
→ 202 Accepted
   headers:  Location: /jobs/j-99
   body={"jobId":"j-99","status":"queued"}

# Later, client polls:
GET /jobs/j-99
→ 200 OK
   body={"jobId":"j-99","status":"running","progress":45}

# Later still:
GET /jobs/j-99
→ 200 OK
   body={"jobId":"j-99","status":"done","result":{...}}

Webhook:

POST /deployments   body={...large job..., "callbackUrl":"https://me.com/hook"}
→ 202 Accepted
   body={"jobId":"j-99"}

# Server POSTs to the callback URL when done:
POST https://me.com/hook
   body={"jobId":"j-99","status":"done","result":{...}}

See the webhooks topic for the pattern in detail.

How to tell

If an API returns 200/201 with the result, it is synchronous. If an API returns 202 Accepted with a jobId / Location, it is asynchronous. The 202 is the convention. Follow the Location header to the status endpoint.

FAQ

Is GraphQL REST or RPC? Neither cleanly. GraphQL has one URL (/graphql), you POST a query describing exactly the fields you want. Call it its own category. Not on 200-901.

Is Cisco NETCONF REST or RPC? RPC. NETCONF is defined as RPC-over-SSH with XML payloads. RESTCONF is the REST transformation of the same data model.

Why would anyone pick RPC over REST? Streaming (gRPC supports server-push); strict typing with Protocol Buffers; existing codebases. For new synchronous HTTP APIs, REST wins.

Is async always better for big jobs? Yes, once a job exceeds a few seconds. HTTP timeouts, proxy limits and load balancer idle timers all bite long-held connections.