Versioning best practices in Rest API - Mini Project: Build & Apply

Versioning Best Practices in REST API

📖 Scenario: You are building a simple REST API for a book store. Over time, you want to improve your API without breaking existing clients. To do this, you will add versioning to your API endpoints.

🎯 Goal: Create a basic REST API with versioning in the URL path. You will start with version 1 of the API, then add version 2 with a small change. Finally, you will print the API endpoints to show the versioning.

📋 What You'll Learn

Create a dictionary called api_v1 with two endpoints: /books and /authors.

Create a dictionary called api_v2 with the same endpoints but add a new endpoint /publishers.

Create a dictionary called api_versions that maps version strings 'v1' and 'v2' to the respective API dictionaries.

Print all API endpoints grouped by version.

💡 Why This Matters

🌍 Real World

Versioning APIs is important when you want to improve or change your service without breaking existing users. This project shows a simple way to organize and display API versions.

💼 Career

Understanding API versioning is essential for backend developers, API designers, and anyone working with web services to ensure smooth updates and client compatibility.

1

Create API version 1 endpoints

Create a dictionary called api_v1 with these exact keys and values: '/books': 'List all books' and '/authors': 'List all authors'.

Rest API

# Create the api_v1 dictionary with endpoints
# Your code here

Hint

Use curly braces {} to create a dictionary. Use colons : to assign values to keys.

2

Create API version 2 endpoints

Create a dictionary called api_v2 with these exact keys and values: '/books': 'List all books', '/authors': 'List all authors', and '/publishers': 'List all publishers'.

Rest API

api_v1 = {
    '/books': 'List all books',
    '/authors': 'List all authors'
}
# Create the api_v2 dictionary with endpoints
# Your code here

Hint

Remember to add the new endpoint '/publishers' with its description.

3

Map API versions to their endpoints

Create a dictionary called api_versions that maps the string 'v1' to api_v1 and 'v2' to api_v2.

Rest API

api_v1 = {
    '/books': 'List all books',
    '/authors': 'List all authors'
}

api_v2 = {
    '/books': 'List all books',
    '/authors': 'List all authors',
    '/publishers': 'List all publishers'
}
# Create the api_versions dictionary mapping 'v1' and 'v2' to api_v1 and api_v2
# Your code here

Hint

Use the version strings as keys and the API dictionaries as values.

4

Print all API endpoints by version

Use a for loop with variables version and endpoints to iterate over api_versions.items(). Inside the loop, print the version and then print each endpoint and its description from endpoints.items().

Rest API

api_v1 = {
    '/books': 'List all books',
    '/authors': 'List all authors'
}

api_v2 = {
    '/books': 'List all books',
    '/authors': 'List all authors',
    '/publishers': 'List all publishers'
}

api_versions = {
    'v1': api_v1,
    'v2': api_v2
}

# Print all API endpoints grouped by version
# Your code here

Hint

Use nested loops to print each version and its endpoints. Use f-strings for formatting.

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