Media type versioning in Rest API - Mini Project: Build & Apply

Media Type Versioning in REST API

📖 Scenario: You are building a simple REST API for a book store. You want to support versioning of your API using media type versioning. This means clients specify the API version in the Accept header using custom media types.For example, application/vnd.bookstore.v1+json for version 1 and application/vnd.bookstore.v2+json for version 2.

🎯 Goal: Create a basic REST API endpoint that returns book data. Implement media type versioning so the API returns different responses depending on the version specified in the Accept header.

📋 What You'll Learn

Create a dictionary called books with two entries: "id": 1, "title": "The Great Gatsby" and "id": 2, "title": "1984".

Create a variable called supported_versions that lists the supported media types for version 1 and version 2.

Write a function called get_books that takes a media_type string and returns the book data formatted differently depending on the version in the media type.

Print the output of get_books when called with "application/vnd.bookstore.v1+json" and "application/vnd.bookstore.v2+json".

💡 Why This Matters

🌍 Real World

Media type versioning helps APIs evolve without breaking existing clients by letting them request specific versions.

💼 Career

Understanding API versioning is important for backend developers and API designers to maintain and improve web services safely.

1

DATA SETUP: Create the books dictionary

Create a dictionary called books with these exact entries: {1: {"id": 1, "title": "The Great Gatsby"}, 2: {"id": 2, "title": "1984"}}.

Rest API

# Create the books dictionary with two entries
# Your code here

Hint

Use a dictionary with keys 1 and 2. Each key maps to another dictionary with keys id and title.

2

CONFIGURATION: Define supported media type versions

Create a list called supported_versions containing the strings "application/vnd.bookstore.v1+json" and "application/vnd.bookstore.v2+json".

Rest API

books = {
    1: {"id": 1, "title": "The Great Gatsby"},
    2: {"id": 2, "title": "1984"}
}
# Create the supported_versions list
# Your code here

Hint

Use a list with the two exact media type strings for version 1 and version 2.

3

CORE LOGIC: Write the get_books function with media type versioning

Write a function called get_books that takes a parameter media_type. If media_type is "application/vnd.bookstore.v1+json", return a list of book titles. If it is "application/vnd.bookstore.v2+json", return the full book dictionaries as a list. Use the books dictionary defined earlier.

Rest API

books = {
    1: {"id": 1, "title": "The Great Gatsby"},
    2: {"id": 2, "title": "1984"}
}
supported_versions = [
    "application/vnd.bookstore.v1+json",
    "application/vnd.bookstore.v2+json"
]
# Write the get_books function below
# Your code here

Hint

Use an if statement to check the media_type. Return a list of titles for v1, and full book dictionaries for v2.

4

OUTPUT: Print the results for both media types

Print the result of calling get_books with "application/vnd.bookstore.v1+json" and then with "application/vnd.bookstore.v2+json".

Rest API

books = {
    1: {"id": 1, "title": "The Great Gatsby"},
    2: {"id": 2, "title": "1984"}
}
supported_versions = [
    "application/vnd.bookstore.v1+json",
    "application/vnd.bookstore.v2+json"
]

def get_books(media_type):
    if media_type == "application/vnd.bookstore.v1+json":
        return [book["title"] for book in books.values()]
    elif media_type == "application/vnd.bookstore.v2+json":
        return list(books.values())
    else:
        return []

# Print the output for both media types
# Your code here

Hint

Use two print statements to show the output for each media type version.

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