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.

Practice

1. What is the main reason to use versioning in a REST API?

easy

A. To hide the API from users

B. To make the API faster

C. To reduce the number of API endpoints

D. To keep the API stable and avoid breaking existing clients

Solution

1. Step 1: Understand API stability

   Versioning helps keep the API stable by allowing changes without breaking existing users.

2. Step 2: Identify the main goal of versioning

   The main goal is to avoid breaking existing clients when the API changes.

3. Final Answer:

   To keep the API stable and avoid breaking existing clients -> Option D

4. Quick Check:

   Versioning = Stability [OK]

Hint: Versioning protects old users from breaking changes [OK]

Common Mistakes:

• Thinking versioning makes API faster
• Believing versioning reduces endpoints
• Assuming versioning hides the API

2. Which of the following is a correct way to include versioning in a REST API URL?

easy

A. /api/v1/users

B. /api/users/v1

C. /v1/api/users

D. /users/api/v1

Solution

1. Step 1: Identify common versioning URL pattern

   The standard practice is to put the version right after the base API path, like /api/v1/.

2. Step 2: Check each option

   Only /api/v1/users follows the common pattern where version is after /api/.

3. Final Answer:

   /api/v1/users -> Option A

4. Quick Check:

   Version in URL path = /api/v1/ [OK]

Hint: Version usually goes right after /api/ in URL [OK]

Common Mistakes:

• Placing version after resource name
• Putting version before /api/
• Adding version at the end of URL

3. Given this API request header: Accept: application/vnd.example.v2+json, what version of the API is being requested?

medium

A. Version 3

B. Version 1

C. Version 2

D. No version specified

Solution

1. Step 1: Analyze the Accept header format

   The header uses media type versioning with 'v2' indicating version 2.

2. Step 2: Identify the version number

   The 'v2' in 'application/vnd.example.v2+json' means version 2 is requested.

3. Final Answer:

   Version 2 -> Option C

4. Quick Check:

   Header v2 means API version 2 [OK]

Hint: Look for 'v' followed by number in Accept header [OK]

Common Mistakes:

• Ignoring 'v2' and assuming version 1
• Confusing media type with version
• Assuming no version if not in URL

4. You have an API that uses URL versioning like /api/v1/resource. You want to upgrade to version 2 but keep version 1 working. What is the best fix if your current code overwrites the version path and breaks v1?

medium

A. Create separate routes for /api/v1/resource and /api/v2/resource

B. Remove version from URL and use query parameters instead

C. Only keep /api/v2/resource and delete /api/v1/resource

D. Use the same code for both versions without changes

Solution

1. Step 1: Understand versioning goal

   Versioning allows multiple versions to coexist so old clients keep working.

2. Step 2: Fix route handling

   Separate routes for each version keep both versions working without conflict.

3. Final Answer:

   Create separate routes for /api/v1/resource and /api/v2/resource -> Option A

4. Quick Check:

   Separate routes = keep versions working [OK]

Hint: Keep old and new versions on separate routes [OK]

Common Mistakes:

• Overwriting old version routes
• Removing version info completely
• Using same code for different versions

5. You want to design an API versioning strategy that allows clients to specify the version either in the URL path or in a custom header. Which approach best follows versioning best practices?

hard

A. Ignore versioning and always use the latest API version

B. Support both methods but clearly document and prefer one as primary

C. Allow clients to mix URL and header versions freely without restrictions

D. Use query parameters for versioning only

Solution

1. Step 1: Understand consistency in versioning

   Best practice is to be consistent and clear about versioning methods.

2. Step 2: Choose a primary versioning method

   Supporting both but preferring one and documenting it helps developers avoid confusion.

3. Final Answer:

   Support both methods but clearly document and prefer one as primary -> Option B

4. Quick Check:

   Clear, consistent versioning = best practice [OK]

Hint: Pick one versioning method as main, document it well [OK]

Common Mistakes:

• Mixing versions without clear rules
• Ignoring versioning and breaking clients
• Using only query parameters without reason