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.