Media type versioning in Rest API - Step-by-Step Execution

Concept Flow - Media type versioning

Client sends HTTP request

↓

Server reads Accept header

↓

Parse media type and version

↓

Match version to API handler

↓

Process request with correct version

↓

Send response with versioned media type

↓

Client receives response

The client sends a request with a media type specifying the API version. The server reads this, selects the correct version handler, processes the request, and responds with the matching versioned media type.

Execution Sample

Rest API

GET /users HTTP/1.1
Accept: application/vnd.example.v2+json

Response:
Content-Type: application/vnd.example.v2+json
Body: {"users": [...] }

Client requests version 2 of the users API by specifying it in the Accept header; server responds with version 2 media type and data.

Execution Table

Step	Action	Header/Value	Server Decision	Response Header	Response Body
1	Client sends request	Accept: application/vnd.example.v2+json	Reads Accept header, detects version 2
2	Server selects handler		Uses API version 2 handler
3	Server processes request		Fetches users data for v2
4	Server sends response			Content-Type: application/vnd.example.v2+json	{"users": [...] }
5	Client receives response				Processes data as version 2 format

💡 Request completed with version 2 media type; client and server agree on API version.

Variable Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	Final
Accept Header	None	application/vnd.example.v2+json	application/vnd.example.v2+json	application/vnd.example.v2+json	application/vnd.example.v2+json
API Version	None	Detected v2	v2	v2	v2
Response Content-Type	None	None	None	Set to v2 media type	application/vnd.example.v2+json
Response Body	None	None	None	Set with v2 users data	{"users": [...] }

Key Moments - 2 Insights

Why does the server look at the Accept header instead of the URL to determine the API version?

Because media type versioning uses the Accept header to specify the version, allowing the URL to stay clean and stable. This is shown in execution_table row 1 where the server reads the Accept header to detect version 2.

What happens if the client sends an Accept header with a version the server does not support?

The server cannot find a matching handler and usually returns an error or default version. This is implied by the server decision step in execution_table row 2 where it selects the handler based on the version.

Visual Quiz - 3 Questions

Look at the execution_table, what version does the server detect from the Accept header at step 1?

A v2

B v3

C v1

D No version detected

💡 Hint

Check the 'Header/Value' and 'Server Decision' columns in row 1 of execution_table.

At which step does the server set the response Content-Type header to the versioned media type?

A Step 3

B Step 4

C Step 2

D Step 5

💡 Hint

Look at the 'Response Header' column in execution_table rows.

If the client changed the Accept header to 'application/vnd.example.v1+json', how would the API Version variable change in variable_tracker?

A It would stay as v2

B It would become None

C It would change to v1

D It would become v3

💡 Hint

Refer to the 'API Version' row in variable_tracker and how it matches Accept header values.

Concept Snapshot

Media type versioning uses the Accept header to specify API version.
Server reads Accept header to select correct API version handler.
Response Content-Type matches requested version.
Keeps URLs clean and supports multiple API versions.
Client and server agree on version via media type.
Example: Accept: application/vnd.example.v2+json

Full Transcript

Media type versioning is a way to manage different versions of an API by using the HTTP Accept header. The client sends a request with an Accept header that includes the version number in the media type, like application/vnd.example.v2+json. The server reads this header, detects the requested version, and selects the appropriate API handler for that version. It then processes the request and sends back a response with the Content-Type header set to the same versioned media type. This approach keeps the URL stable and clean while allowing multiple API versions to coexist. The execution table shows the step-by-step flow from client request to server response, tracking how the Accept header is read, the version is detected, and the response is formed. The variable tracker shows how key variables like Accept header, API version, response Content-Type, and response body change during the process. Common confusions include why the Accept header is used instead of the URL and what happens if an unsupported version is requested. The visual quiz tests understanding of these steps and variable changes.

Practice

1. What is the main purpose of using media type versioning in REST APIs?

easy

A. To allow clients to specify API versions via custom content types

B. To encrypt API data for security

C. To speed up API response times

D. To change the API URL structure frequently

Solution

1. Step 1: Understand media type versioning concept

   Media type versioning lets clients request specific API versions by setting custom content types in headers.

2. Step 2: Identify the main purpose

   This approach helps keep APIs backward compatible by allowing multiple versions to coexist.

3. Final Answer:

   To allow clients to specify API versions via custom content types -> Option A

4. Quick Check:

   Media type versioning = clients specify versions [OK]

Hint: Remember: version info goes in content type headers [OK]

Common Mistakes:

• Confusing versioning with encryption
• Thinking URL changes are required
• Assuming it improves speed directly

2. Which HTTP header is commonly used by clients to specify the API version in media type versioning?

easy

A. Content-Type

B. Accept

C. Authorization

D. User-Agent

Solution

1. Step 1: Identify header for version negotiation

   The client uses the Accept header to tell the server which media type and version it wants.

2. Step 2: Differentiate from other headers

   Content-Type is for request body format, Authorization is for credentials, and User-Agent identifies the client software.

3. Final Answer:

   Accept -> Option B

4. Quick Check:

   Version in Accept header [OK]

Hint: Accept header tells server what version client wants [OK]

Common Mistakes:

• Using Content-Type instead of Accept for versioning
• Confusing Authorization with version info
• Thinking User-Agent controls version

3. Given this HTTP Accept header:
Accept: application/vnd.example.v2+json
What version of the API is the client requesting?

medium

A. Version 3

B. Version 1

C. Version 2

D. No version specified

Solution

1. Step 1: Parse the media type string

   The media type is application/vnd.example.v2+json. The .v2 part indicates version 2.

2. Step 2: Confirm version number meaning

   The v2 suffix is a common pattern to specify API version 2 in media type versioning.

3. Final Answer:

   Version 2 -> Option C

4. Quick Check:

   v2 in media type means version 2 [OK]

Hint: Look for .vX in media type for version number [OK]

Common Mistakes:

• Ignoring the .v2 and picking version 1
• Confusing +json suffix as version
• Assuming no version if not in URL

4. A client sends this header:
Accept: application/vnd.example.v1+json
But the server responds with version 2 data. What is the likely cause?

medium

A. Accept header syntax is invalid

B. Client sent wrong Content-Type header

C. Server does not support version 2

D. Server ignores Accept header and defaults to latest version

Solution

1. Step 1: Analyze client request and server response

   The client requests version 1 via Accept header, but server returns version 2 data.

2. Step 2: Identify server behavior

   This usually means the server ignores the Accept header and serves the latest version by default.

3. Final Answer:

   Server ignores Accept header and defaults to latest version -> Option D

4. Quick Check:

   Server ignoring Accept header causes version mismatch [OK]

Hint: Mismatch means server likely ignores Accept header [OK]

Common Mistakes:

• Blaming client Content-Type instead of Accept
• Assuming Accept header syntax error without checking
• Thinking server lacks version 2 support

5. You want to support two API versions simultaneously using media type versioning. Which server behavior best supports this?

hard

A. Parse the Accept header and return data matching the requested version

B. Ignore Accept header and always return version 2 data

C. Use URL path versioning instead of media type versioning

D. Return an error if Accept header version is not latest

Solution

1. Step 1: Understand requirement for simultaneous version support

   To support multiple versions, the server must detect which version the client wants.

2. Step 2: Identify correct server behavior

   Parsing the Accept header and returning matching version data allows backward compatibility and coexistence.

3. Final Answer:

   Parse the Accept header and return data matching the requested version -> Option A

4. Quick Check:

   Server parses Accept header to serve requested version [OK]

Hint: Server must read Accept header to serve correct version [OK]

Common Mistakes:

• Ignoring Accept header and forcing one version
• Switching to URL versioning instead of media type
• Returning errors instead of supporting old versions