How to Implement Filtering in REST API: Simple Guide

To implement filtering in a REST API, use query parameters in the request URL to specify filter criteria. The server reads these parameters, applies the filters to the data source, and returns only matching results. This approach keeps APIs flexible and efficient for clients.

Syntax

Filtering in REST APIs is commonly done using query parameters in the URL. The general syntax is:

GET /resource?field1=value1&field2=value2

Here:

• GET is the HTTP method to retrieve data.
• /resource is the API endpoint.
• field1=value1 and field2=value2 are filters applied to the data.

http

GET /items?category=books&price_lt=20

Example

This example shows a simple REST API built with Python and Flask that filters a list of items by category and maximum price using query parameters.

python

from flask import Flask, request, jsonify

app = Flask(__name__)

items = [
    {"id": 1, "name": "Book A", "category": "books", "price": 15},
    {"id": 2, "name": "Pen", "category": "stationery", "price": 5},
    {"id": 3, "name": "Book B", "category": "books", "price": 25},
    {"id": 4, "name": "Notebook", "category": "stationery", "price": 10}
]

@app.route('/items')
def get_items():
    category = request.args.get('category')
    price_lt = request.args.get('price_lt', type=float)

    filtered = items
    if category:
        filtered = [item for item in filtered if item['category'] == category]
    if price_lt is not None:
        filtered = [item for item in filtered if item['price'] < price_lt]

    return jsonify(filtered)

if __name__ == '__main__':
    app.run(debug=True)

Output

Running the server and requesting GET /items?category=books&price_lt=20 returns:
[
  {"id": 1, "name": "Book A", "category": "books", "price": 15}
]

Common Pitfalls

Common mistakes when implementing filtering in REST APIs include:

• Not validating query parameters, which can cause errors or security issues.
• Ignoring case sensitivity, leading to unexpected filter results.
• Returning all data without filtering when parameters are missing, which can overload clients.
• Using complex filtering logic in the URL making it hard to maintain.

Always validate and sanitize inputs, and keep filtering logic clear and simple.

python

Wrong approach (no validation):

@app.route('/items')
def get_items():
    category = request.args.get('category')
    filtered = [item for item in items if item['category'] == category]
    return jsonify(filtered)

# This fails if category is None

Right approach (with validation):

@app.route('/items')
def get_items():
    category = request.args.get('category')
    if category is None:
        return jsonify(items)  # or return error
    filtered = [item for item in items if item['category'] == category]
    return jsonify(filtered)

Quick Reference

Concept	Description	Example
Query Parameters	Used to specify filters in the URL	/items?category=books&price_lt=20
Validation	Check and sanitize inputs to avoid errors	if category is None: return all or error
Multiple Filters	Combine filters with & in URL	/items?category=books&price_lt=20
Case Sensitivity	Consider normalizing input for consistent filtering	category.lower() == item['category'].lower()
Response	Return filtered data as JSON	return jsonify(filtered_items)

Key Takeaways

Use query parameters in the URL to specify filter criteria for REST API endpoints.

Always validate and sanitize filter inputs to prevent errors and security issues.

Combine multiple filters by joining query parameters with & in the request URL.

Return only the filtered data as JSON to keep responses efficient and relevant.

Keep filtering logic simple and clear for easy maintenance and scalability.