Identifying Collection Resources and Documenting Filters

What is this Guide About?

This guide helps you identify resources from your ER diagram and document filtering operations for your REST API design.

---

Step 1: Review Your ER Diagram Tables

List all tables from your ER diagram with your field counts:

Table Name	Number of Fields
(table 1)	?
(table 2)	?
…	…

Requirement: Each table must have at least 5 fields.

---

Step 2: Sort Tables by Field Count

Reorder your tables from highest to lowest number of fields:

Rank	Table Name	Number of Fields
1
2
3
4
…

---

Step 3: Select Tables for Collection Resources

• Team of 3: Select the top 3 tables
• Team of 4: Select the top 4 tables

These become your primary collection resources.

---

Step 4: Convert Tables to PARENT Collection Resources

IMPORTANT: You must identify parent (top-level) collections FIRST before identifying sub-collections. Sub-collections are derived from the relationships between parent collections.

For each selected table, create a parent collection resource using plural nouns:

Table Name (Singular)	Collection Resource URI
Mission	/missions
Astronaut	/astronauts
Planet	/planets
Spacecraft	/spacecraft

Naming Rules:

• Use lowercase
• Use plural nouns (e.g., mission → missions)
• Use hyphens for multi-word names (e.g., launch-sites)

---

Step 5: Assign Collections to Team Members

Team Member	Assigned Collection Resource
Member 1	/collection1
Member 2	/collection2
Member 3	/collection3
Member 4*	/collection4

*If team of 4

NOTE: If there are not enough parent collection resources for all team members, a team member may select a sub-collection instead, provided that the sub-collection has more than 5 fields.

Example: If your team has 4 members but only 3 parent collections, one member can take a sub-collection like /missions/{missionId}/crew if the crew table has at least 5 fields.

---

Step 6: Identify Sub-Collections (Nested Resources)

IMPORTANT: This step can ONLY be done AFTER you have identified all parent collections in Steps 3-5. Sub-collections are based on the relationships (foreign keys) between your parent collections.

Why this order matters:

• You cannot define /missions/{missionId}/crew without first knowing that missions is a parent collection
• Sub-collections represent how parent resources relate to each other
• The foreign keys in your ER diagram tell you which resources can be nested under others

Sub-collections represent relationships between resources. Look at your ER diagram for:

• One-to-One relationships
• One-to-Many relationships
• Many-to-Many relationships (via junction tables)

---

One-to-One Relationships

A one-to-one relationship links a single parent resource to a single child resource.

Pattern:

/parent-collection/{parentId}/child-singleton

Examples:

Relationship	URI Pattern	Description
Mission has one Commander	/missions/{missionId}/commander	Each mission has exactly one commander
Astronaut has one MedicalRecord	/astronauts/{astronautId}/medical-record	Each astronaut has one medical record
Spacecraft has one Manifest	/spacecraft/{spacecraftId}/manifest	Each spacecraft has one cargo manifest
Planet has one Atmosphere	/planets/{planetId}/atmosphere	Each planet has one atmosphere profile

Note: For one-to-one, the nested resource is a singleton (singular noun), not a collection.

---

One-to-Many Relationships (Sub-Collections)

A one-to-many relationship links a single parent to multiple children.

Pattern:

/parent-collection/{parentId}/child-collection

Examples:

Relationship	Sub-Collection URI
Mission has many Crew Members	/missions/{missionId}/crew
Planet has many Moons	/planets/{planetId}/moons
Spacecraft has many Components	/spacecraft/{spacecraftId}/components
Astronaut has many Missions	/astronauts/{astronautId}/missions

---

Many-to-Many Relationships

Many-to-many relationships are typically represented through a junction/associative table. You can expose them from either side.

Pattern:

/resource-a/{aId}/resource-b
/resource-b/{bId}/resource-a

Examples:

Relationship	URI Patterns
Astronauts ↔ Missions	/astronauts/{astronautId}/missions and /missions/{missionId}/crew
Planets ↔ Missions	/planets/{planetId}/missions and /missions/{missionId}/planets
Spacecraft ↔ Components	/spacecraft/{spacecraftId}/components and /components/{componentId}/spacecraft

---

Sub-Resource Template

Relationship Type	Parent Collection	Child Resource	Full URI Pattern
One-to-One	/parents	/child (singular)	/parents/{parentId}/child
One-to-Many	/parents	/children (plural)	/parents/{parentId}/children
Many-to-Many	/parents	/others (plural)	/parents/{parentId}/others

---

Step 7: Create Filter Tables (5 Fields Per Collection)

Each team member creates a filter table for their assigned collection with 5 filterable fields.

Filter Table Template:

Collection: /your-collection

#	Field Name	Data Type	Filter Parameter	Example Query
1
2
3
4
5

Example Filter Table:

Collection: /missions

#	Field Name	Data Type	Filter Parameter	Example Query
1	status	String	?status=active	GET /missions?status=active
2	launchDate	Date	?launch_date_after=2024-01-01	GET /missions?launch_date_after=2024-01-01
3	duration	Integer	?duration_min=30&duration_max=365	GET /missions?duration_min=30&duration_max=365
4	destination	String	?destination=Mars	GET /missions?destination=Mars
5	crewed	Boolean	?crewed=true	GET /missions?crewed=true

---

Step 8: Document Filter Types by Data Type

Use appropriate filter operators based on data type:

Data Type	Recommended Filter Operators	Example
String	exact match, contains, startsWith	?name=Apollo, ?name_contains=Mars
Number	equals, min, max, range	?crewSize=6, ?duration_min=30&duration_max=365
Date	before, after, between	?launch_date_after=2024-01-01
Boolean	equals	?crewed=true
Enum	equals, in (multiple values)	?status=active, ?status=planned,launched

---

Step 9: Add Sorting Parameters

For each collection, define sortable fields:

Collection: /your-collection

Sortable Field	Sort Parameter Example
name	?sort=name or ?sort=-name (desc)
launchDate	?sort=launchDate
duration	?sort=-duration (longest first)

---

Step 10: Add Pagination Parameters

Standard pagination parameters for all collections:

Parameter	Description	Example
page	Page number (starts at 1)	?page=2
limit	Items per page	?limit=20
offset	Skip N items (alternative)	?offset=20

Combined Example:

GET /missions?status=active&destination=Mars&sort=-launchDate&page=1&limit=10

---

Step 11: Map HTTP Status Codes to Operations (Team Task)

This section must be completed by ALL team members together.

HTTP status codes indicate the result of an HTTP request. Your API must return appropriate status codes for each operation.

---

Success Status Codes (2xx)

Status Code	Name	When to Use
200	OK	Successful GET, PUT, PATCH requests that return data
201	Created	Successful POST request that creates a new resource
204	No Content	Successful DELETE request (no response body)

---

Client Error Status Codes (4xx)

Status Code	Name	When to Use
400	Bad Request	Invalid request syntax, malformed JSON, validation errors
401	Unauthorized	Missing or invalid authentication credentials
403	Forbidden	Valid credentials but insufficient permissions
404	Not Found	Resource does not exist at the given URI
405	Method Not Allowed	HTTP method not supported for this endpoint
409	Conflict	Request conflicts with current state (e.g., duplicate entry)
422	Unprocessable Entity	Valid syntax but semantic errors (e.g., invalid field values)

---

Server Error Status Codes (5xx)

Status Code	Name	When to Use
500	Internal Server Error	Unexpected server-side error
503	Service Unavailable	Server temporarily unavailable (maintenance, overload)

---

Complete Documentation Checklist

For each team member’s collection, ensure you have:

• Collection resource URI (plural noun)
• Sub-collections identified (if relationships exist)
• Filter table with 5 fields
• Sorting parameters defined
• Pagination parameters defined
• Example queries documented

---

Summary Template Per Team Member

Team Member: [Name]

Assigned Collection: /collection-name

1. Collection URI: /collection-name

2. Singleton URI: /collection-name/{id}

3. Sub-Collections:

Sub-Collection	URI Pattern

4. Filter Table (5 Fields):

#	Field	Type	Parameter	Example
1
2
3
4
5

5. Sorting:

• ?sort=field1
• ?sort=-field2 (descending)

6. Pagination:

• ?page=1&limit=10

---

Quick Reference: URI Patterns

Resource Type	URI Pattern	Example
Collection	/resources	/missions
Singleton	/resources/{id}	/missions/123
Sub-collection	/resources/{id}/subresources	/missions/123/crew
Sub-singleton	/resources/{id}/subresources/{subId}	/missions/123/crew/456
Nested singleton	/resources/{id}/subresource	/missions/123/commander
Filtered	/resources?param=value	/astronauts?nationality=Canadian
Sorted	/resources?sort=field	/missions?sort=launchDate
Paginated	/resources?page=N&limit=M	/planets?page=1&limit=20