Additional Resource for Assignment 1

Understanding REST API Endpoints

What is an Endpoint?

An endpoint is a specific URI where your web service can be accessed. It represents a point of entry to your API where clients can send requests and receive responses.

• Each endpoint is associated with:

  1. A URI path - The address of the resource (e.g., /cameras, /lenses/5)
  2. An HTTP method - The action to perform (GET, POST, PUT, DELETE)

---

Restaurant Menu Analogy

Think of a REST API like a restaurant:

Restaurant	REST API
The menu	The list of endpoints your API offers
A menu item (e.g., “Pasta Carbonara”)	An endpoint (e.g., /cameras)
Ordering a dish	Making an HTTP request
The kitchen prepares your order	The server processes your request
Food delivered to your table	The response returned (JSON data)

Just like a menu tells you what dishes are available and what you can order, your API documentation tells clients what endpoints exist and what data they can request.

Types of Resources

Type	Description	Example
Collection	Returns multiple resources	GET /cameras → Returns all cameras
Singleton	Returns a single resource	GET /cameras/3 → Returns camera with ID 3
Sub-collection	Returns related resources nested under a parent	GET /manufacturers/1/lenses → Returns all lenses made by manufacturer 1

Endpoint Structure

[HTTP Method] [Base URI]/[Resource Path]
     ↓              ↓            ↓
    GET    http://localhost/camera-api/cameras/5

• Base URI: Where your API is hosted (e.g., http://localhost/camera-api)
• Resource Path: Identifies what data you’re accessing (e.g., /cameras/5)

---

Understanding Range Filters & Implementation Examples

What is Aperture Range?

Aperture is the maximum opening of the lens diaphragm, measured in f-stops (e.g., f/1.4, f/2.8, f/4.0).

• Definition: The widest opening the lens can achieve (lower number = wider opening = more light)
• Measurement: Expressed as f-number (e.g., f/1.2, f/1.4, f/2.8)
• Database field: aperture_max in the lenses table

How Range Filtering Works

“Range” means you can filter by specifying minimum and/or maximum values using _min and _max suffixes as query string parameters:

Filter Examples:

GET /api/lenses?aperture_max_min=1.2

Find lenses with maximum aperture of at least f/1.2 (very fast lenses)

GET /api/lenses?aperture_max_max=2.8

Find lenses with maximum aperture no wider than f/2.8

GET /api/lenses?aperture_max_min=1.4&aperture_max_max=2.8

Find lenses with maximum aperture between f/1.4 and f/2.8

Practical Use Cases to Implement

1. Portrait Photography: GET /api/lenses?aperture_max_max=1.8 (fast lenses for bokeh)
2. Budget Lenses: GET /api/lenses?aperture_max_min=3.5 (slower but more affordable)
3. Professional: GET /api/lenses?aperture_max_min=1.2&aperture_max_max=2.8 (high-quality fast lenses)

Other Range Filter Examples

Price Range:

GET /api/cameras?price_min=1000.00&price_max=3000.00

Camera bodies costing between $1000-$3000

Focal Length Range:

GET /api/lenses?focal_length_min_min=24&focal_length_max_max=70

Standard zoom range lenses (24-70mm coverage)

Weight Range:

GET /api/cameras?weight_min=400&weight_max=800

Camera bodies weighing between 400-800 grams

ISO Range:

GET /api/sensors?iso_max_min=51200

Sensors with high ISO capability (at least 51200)

Date Ranges:

GET /api/cameras?release_date_after=2020-01-01&release_date_before=2023-12-31

Products released between Jan 1, 2020 and Dec 31, 2023

Multiple Filter Combinations:

GET /api/cameras?price_min=1500.00&body_type=Mirrorless&has_ibis=true

Mirrorless cameras with IBIS costing at least $1500

---

Understanding “Minimum Count” Filters

Some filters use ‘minimum count’ logic - these filter based on how many related items exist. These require database aggregations (COUNT queries with HAVING clauses).

What is “Camera Count Minimum”?

Camera count minimum filters manufacturers based on how many different camera models they produce.

• Database Logic: COUNT(camera_bodies.body_id) >= minimum_value
• Use Case: Find established manufacturers with extensive camera lineups
• Implementation: Requires JOIN between manufacturers and camera_bodies tables with GROUP BY and HAVING

Examples:

GET /api/manufacturers?camera_count_min=10

Find manufacturers who produce at least 10 different camera models

GET /api/manufacturers?camera_count_min=5&country=Japan

Find Japanese manufacturers who make at least 5 camera models

Other ‘Minimum Count’ Filter Examples

Lens Count Minimum:

GET /api/manufacturers?lens_count_min=15

Manufacturers who produce at least 15 lens models

Implementation Notes

SQL Pattern for Count Minimums:

SELECT m.* FROM manufacturers m
LEFT JOIN camera_bodies cb ON m.manufacturer_id = cb.manufacturer_id
GROUP BY m.manufacturer_id
HAVING COUNT(cb.body_id) >= :camera_count_min

Key Points

• Requires GROUP BY on the main table’s primary key
• Uses HAVING clause (not WHERE) for aggregate conditions
• May need LEFT JOIN to include entities with zero counts
• More complex than simple field filters - requires aggregate queries

Notes

• All endpoints support HTTP GET with query string parameters for filtering
• Range filters use _min and _max suffixes (e.g., price_min=100&price_max=300)
• Date filters use _after and _before suffixes (e.g., release_date_after=2020-01-01)
• Multiple filters can be combined using & (e.g., ?price_min=100&has_ibis=true)
• All operations are READ-ONLY (no CREATE, UPDATE, DELETE)