Nested Resources Example

This example demonstrates complex nested resource hierarchies with multiple path parameters, following a GitHub-like pattern for organizations, teams, members, and projects.

Features Demonstrated#

Resource Hierarchy#

Organization (Level 1)
    |
    +-- Team (Level 2)
          |
          +-- Member (Level 3)
          |
          +-- Project (Level 3)

Quick Start#

# Generate code and run the server
make demo
 
# Test nested resource endpoints
make test

API Endpoints#

Organizations (1 path parameter)#

Teams (2 path parameters)#

Members (3 path parameters)#

Projects (3 path parameters)#

Example Requests#

Get Organization (1 path parameter)#

curl -X GET http://localhost:8080/api/v1/orgs/org-abc123 \
  -H "Authorization: Bearer test-token"

Get Team (2 path parameters)#

curl -X GET http://localhost:8080/api/v1/orgs/org-abc123/teams/team-xyz789 \
  -H "Authorization: Bearer test-token"

Get Member (3 path parameters - deepest nesting)#

curl -X GET http://localhost:8080/api/v1/orgs/org-abc123/teams/team-xyz789/members/member-456 \
  -H "Authorization: Bearer test-token"

List Teams with Query Parameters#

curl -X GET "http://localhost:8080/api/v1/orgs/org-abc123/teams?page=1&limit=10&include_private=true" \
  -H "Authorization: Bearer test-token"

Create Team (path parameter + body)#

curl -X POST http://localhost:8080/api/v1/orgs/org-abc123/teams \
  -H "Authorization: Bearer test-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Team",
    "description": "A new team",
    "private": false
  }'

Add Member (2 path parameters + body)#

curl -X POST http://localhost:8080/api/v1/orgs/org-abc123/teams/team-xyz789/members \
  -H "Authorization: Bearer test-token" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user-new123",
    "role": 1
  }'

Remove Member (3 path parameters)#

curl -X DELETE http://localhost:8080/api/v1/orgs/org-abc123/teams/team-xyz789/members/member-456 \
  -H "Authorization: Bearer test-token"

Proto Definition Pattern#

Path parameters are automatically extracted from the URL and bound to request fields with matching names:

// Request with 3 path parameters
message GetTeamMemberRequest {
  string org_id = 1;     // Bound from {org_id} in path
  string team_id = 2;    // Bound from {team_id} in path
  string member_id = 3;  // Bound from {member_id} in path
}
 
// Service definition
service OrganizationService {
  rpc GetTeamMember(GetTeamMemberRequest) returns (Member) {
    option (sebuf.http.config) = {
      path: "/orgs/{org_id}/teams/{team_id}/members/{member_id}"
      method: HTTP_METHOD_GET
    };
  }
}

Combining Path and Query Parameters#

message ListTeamMembersRequest {
  // From path
  string org_id = 1;
  string team_id = 2;
 
  // From query string
  int32 page = 3 [(sebuf.http.query) = { name: "page" }];
  int32 limit = 4 [(sebuf.http.query) = { name: "limit" }];
  string role_filter = 5 [(sebuf.http.query) = { name: "role" }];
}

Generated Files#

After running make generate:

api/
  proto/
    models/
      organization.pb.go           # All message types
    services/
      organization_service.pb.go         # Service interface
      organization_service_http.pb.go    # HTTP handlers (12 endpoints!)
      organization_service_http_binding.pb.go  # Request binding
      organization_service_http_config.pb.go   # Server options
      organization_service_http_mock.pb.go     # Mock implementation
docs/
  OrganizationService.openapi.yaml  # OpenAPI with all nested paths
  OrganizationService.openapi.json

Key Concepts#

Path Parameter Binding#

Path parameters like {org_id} are automatically extracted from the URL and bound to the corresponding request message field. The field name must match the path variable name.

Hierarchical Resource Ownership#

The nested URL structure enforces resource ownership:

• A team belongs to an organization
• A member/project belongs to a team within an organization

This is validated by including parent IDs in each request, allowing your service to verify ownership.

REST Best Practices#

This example follows REST conventions:

• Collection endpoints use plural nouns (/orgs, /teams, /members)
• Single resource endpoints include the ID (/orgs/{org_id})
• Nested resources show parent-child relationships in the URL
• HTTP verbs match the operation (GET=read, POST=create, DELETE=remove)