Versioning best practices in Rest API - Step-by-Step Execution

Concept Flow - Versioning best practices

Client sends request

↓

Check API version in request

↓

Match version with supported versions

↓

Process

↓

Send response

The client sends a request specifying an API version. The server checks if this version is supported. If yes, it processes the request; if not, it returns an error.

Execution Sample

Rest API

GET /api/v1/users
Host: example.com

Response: 200 OK
{
  "users": [...] 
}

Client requests user data from version 1 of the API; server responds with user list.

Execution Table

Step	Action	Version Extracted	Version Supported?	Response
1	Receive request GET /api/v1/users	v1	Check if v1 is supported	Pending
2	v1 is supported	v1	Yes	Process request
3	Send response with user data	v1	Yes	200 OK with users
4	Receive request GET /api/v3/users	v3	Check if v3 is supported	Pending
5	v3 is not supported	v3	No	Return 400 Bad Request error

💡 Execution stops when response is sent back to client.

Variable Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	After Step 4	After Step 5	Final
version	null	v1	v1	v1	v3	v3	v3
supported	null	checking	true	true	checking	false	false
response	null	pending	pending	200 OK	pending	pending	400 Bad Request

Key Moments - 2 Insights

Why does the server return an error for version v3?

Because in the execution_table at step 5, the version v3 is not supported, so the server returns a 400 Bad Request error.

How does the server know which version the client requested?

At step 1 and 4 in the execution_table, the server extracts the version from the request URL path (e.g., /api/v1/ or /api/v3/).

Visual Quiz - 3 Questions

Look at the execution_table, what is the response when the client requests version v1?

A 200 OK with users

B 400 Bad Request error

C 404 Not Found

D 500 Internal Server Error

💡 Hint

Check the response column at step 3 for version v1.

At which step does the server determine that version v3 is unsupported?

A Step 2

B Step 5

C Step 4

D Step 3

💡 Hint

Look at the supported column and response at step 5 in the execution_table.

If the client sends a request without a version in the URL, what should the server do according to best practices?

A Assume latest version and process

B Process with oldest version

C Return an error about missing version

D Ignore version and process anyway

💡 Hint

Best practices recommend explicit versioning; see key moments about version extraction.

Concept Snapshot

Versioning Best Practices for REST APIs:
- Include version in URL path (e.g., /api/v1/)
- Server checks requested version against supported versions
- If supported, process request; else return error
- Helps clients use correct API behavior
- Avoids breaking changes for existing clients

Full Transcript

This visual trace shows how a REST API handles versioning. When a client sends a request, the server extracts the version from the URL path. It then checks if this version is supported. If yes, the server processes the request and returns data. If not, it returns an error indicating the version is unsupported. This approach helps maintain compatibility and clear communication between client and server about API versions.