Query parameter versioning in Rest API - Cheat Sheet & Quick Revision

Recall & Review

beginner

What is query parameter versioning in REST APIs?

Query parameter versioning is a way to specify the API version by adding a version number as a parameter in the URL query string, for example: /api/resource?version=1.

beginner

Why use query parameter versioning?

It allows clients to request a specific API version without changing the URL path. This keeps the base URL stable and makes versioning flexible.

beginner

How does the server know which version to serve when using query parameter versioning?

The server reads the version number from the query parameter (like ?version=2) and returns the response formatted for that version.

beginner

Give an example of a URL using query parameter versioning.

An example URL is https://api.example.com/users?version=1, where version=1 tells the server to use version 1 of the API.

intermediate

What is a potential downside of query parameter versioning?

One downside is that caching systems might treat URLs with different query parameters as separate resources, which can complicate caching strategies.

What does query parameter versioning add to the API request URL?

A A version number in the request header

B A version number in the URL path

C A version number in the query string

D A version number in the request body

Query parameter versioning uses the query string to specify the API version, like ?version=1.

Which of these URLs uses query parameter versioning?

A /api/users?version=2

B /api/v2/users

C /api/users

D /api/users/version/2

The version number is passed as a query parameter in option A.

What is a benefit of query parameter versioning?

A Keeps the base URL unchanged

B Requires changing the URL path

C Does not allow versioning

D Only works with POST requests

Query parameter versioning keeps the base URL stable and adds version info in the query string.

How does the server identify the API version in query parameter versioning?

A By reading the request header

B By reading the request body

C By reading the URL path segment

D By reading the query parameter value

The server looks at the query parameter, such as ?version=1, to determine the version.

What is a possible drawback of query parameter versioning?

A It is not supported by REST APIs

B Caching can be less efficient

C It cannot support multiple versions

D It requires changing the URL path

Different query parameters can cause caching systems to treat requests as different resources, complicating caching.

Explain how query parameter versioning works in REST APIs and why it might be used.

Think about how the version is passed and how the server uses it.

Describe one advantage and one disadvantage of using query parameter versioning.

Consider URL stability and caching behavior.

Practice

1. What is the main purpose of using query parameter versioning in REST APIs?

easy

A. To change the main URL path for each API version

B. To allow clients to specify which API version they want using a query string

C. To hide the API version from clients

D. To force all clients to use the latest API version only

Solution

1. Step 1: Understand query parameter versioning concept

   Query parameter versioning lets clients add a version number in the URL query string, like ?version=1.

2. Step 2: Identify the purpose of this method

   This allows clients to choose which API version to use without changing the main URL path.

3. Final Answer:

   To allow clients to specify which API version they want using a query string -> Option B

4. Quick Check:

   Query parameter versioning = client selects version [OK]

Hint: Version in query string means client chooses API version [OK]

Common Mistakes:

• Thinking versioning changes the main URL path
• Assuming versioning hides API versions
• Believing all clients must use latest version only

2. Which of the following is the correct way to request version 2 of an API using query parameter versioning?

easy

A. GET /api/resource/version=2

B. GET /api/version/2/resource

C. GET /api/resource?version=2

D. GET /api/resource#version=2

Solution

1. Step 1: Recall query parameter syntax in URLs

   Query parameters come after a question mark ? and use key=value pairs, e.g., ?version=2.

2. Step 2: Match the correct syntax for versioning

   The correct way to specify version 2 is by adding ?version=2 after the resource path.

3. Final Answer:

   GET /api/resource?version=2 -> Option C

4. Quick Check:

   Query param syntax = ?key=value [OK]

Hint: Query parameters start with ? and use key=value [OK]

Common Mistakes:

• Using slashes instead of query parameters
• Using # instead of ? for query parameters
• Placing version inside the URL path incorrectly

3. Given this API endpoint code snippet handling versioning:

def get_data(request):
    version = request.GET.get('version', '1')
    if version == '1':
        return 'Data from v1'
    elif version == '2':
        return 'Data from v2'
    else:
        return 'Unknown version'

What will be the output if the client calls /api/data?version=2?

medium

A. "Data from v2"

B. "Unknown version"

C. "Data from v1"

D. Error: version parameter missing

Solution

1. Step 1: Extract version from query parameters

   The code gets the version from the query string. If missing, it defaults to '1'. Here, version='2'.

2. Step 2: Check version conditions

   Since version is '2', the code returns 'Data from v2'.

3. Final Answer:

   "Data from v2" -> Option A

4. Quick Check:

   version=2 returns v2 data [OK]

Hint: Check query param value matches version condition [OK]

Common Mistakes:

• Assuming default version is always used
• Confusing string and integer comparison
• Expecting error when version is provided

4. Consider this code snippet for versioning:

def api_handler(request):
    version = request.GET['version']
    if version == '1':
        return 'Version 1'
    else:
        return 'Other version'

What error will occur if the client calls /api/data without a version parameter?

medium

A. KeyError because 'version' key is missing

B. SyntaxError in code

C. Returns 'Version 1' by default

D. Returns 'Other version'

Solution

1. Step 1: Understand how version is accessed

   The code uses request.GET['version'] which raises KeyError if 'version' is missing.

2. Step 2: Analyze call without version parameter

   Calling without ?version=... means 'version' key is missing, causing KeyError.

3. Final Answer:

   KeyError because 'version' key is missing -> Option A

4. Quick Check:

   Missing key access causes KeyError [OK]

Hint: Access query keys safely to avoid KeyError [OK]

Common Mistakes:

• Assuming default version is used automatically
• Expecting no error when parameter is missing
• Confusing KeyError with SyntaxError

5. You want to support versions 1 and 2 of your API using query parameter versioning. Version 1 returns a list of users as strings, and version 2 returns a list of user objects with 'name' and 'id'. Which approach correctly handles this in a single endpoint?

hard

A. Return an error if version parameter is missing or unknown

B. Change the URL path to /v1/users and /v2/users instead of query parameters

C. Ignore the version parameter and always return the latest format

D. Use ?version=1 to return ['Alice', 'Bob'], and ?version=2 to return [{'name':'Alice','id':1},{'name':'Bob','id':2}]

Solution

1. Step 1: Understand query parameter versioning usage

   Clients specify version using ?version=1 or ?version=2 in the same URL.

2. Step 2: Return different data formats based on version

   Return simple list of strings for version 1, and detailed objects for version 2, matching client request.

3. Final Answer:

   Use ?version=1 to return ['Alice', 'Bob'], and ?version=2 to return [{'name':'Alice','id':1},{'name':'Bob','id':2}] -> Option D

4. Quick Check:

   Query param version controls response format [OK]

Hint: Return data format based on version query param [OK]

Common Mistakes:

• Changing URL path instead of using query parameters
• Ignoring version parameter and mixing formats
• Returning errors unnecessarily for missing versions