Yellow Pages API Reference

All Yellow Pages endpoints are served under the /api/v1/catalog prefix via the gateway.

Endpoints

Method	Path	Description
GET	/api/v1/catalog/services	List all services
POST	/api/v1/catalog/services	Register a service
GET	/api/v1/catalog/services/:id	Get service by ID or name
DELETE	/api/v1/catalog/services/:id	Remove a service
POST	/api/v1/catalog/services/:id/dependencies	Add dependency
GET	/api/v1/catalog/systems	List systems
POST	/api/v1/catalog/systems	Create system
GET	/api/v1/catalog/owners	List owners
POST	/api/v1/catalog/owners	Create owner
GET	/api/v1/catalog/search?q=<term>	Full-text search
GET	/api/v1/catalog/deps/:id?direction=up|down	Dependency graph traversal

Examples

Register a Service

curl -X POST http://localhost:3000/api/v1/catalog/services \
  -H "Content-Type: application/json" \
  -d '{
    "name": "payment-api",
    "description": "Handles payment processing",
    "tags": ["payments", "core"],
    "system": "billing-system",
    "owner": "platform-team"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "a1b2c3d4",
    "name": "payment-api",
    "description": "Handles payment processing",
    "tags": ["payments", "core"],
    "system": "billing-system",
    "owner": "platform-team",
    "dependencies": [],
    "createdAt": "2026-03-05T12:00:00.000Z",
    "updatedAt": "2026-03-05T12:00:00.000Z"
  }
}

List All Services

curl http://localhost:3000/api/v1/catalog/services

Response:

{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4",
      "name": "payment-api",
      "description": "Handles payment processing",
      "tags": ["payments", "core"],
      "system": "billing-system",
      "owner": "platform-team",
      "dependencies": [],
      "createdAt": "2026-03-05T12:00:00.000Z",
      "updatedAt": "2026-03-05T12:00:00.000Z"
    }
  ]
}

Get a Service by ID or Name

# By ID
curl http://localhost:3000/api/v1/catalog/services/a1b2c3d4

# By name
curl http://localhost:3000/api/v1/catalog/services/payment-api

Search Services

curl "http://localhost:3000/api/v1/catalog/search?q=payment"

Response:

{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4",
      "name": "payment-api",
      "description": "Handles payment processing",
      "tags": ["payments", "core"]
    }
  ]
}

Add a Dependency

curl -X POST http://localhost:3000/api/v1/catalog/services/a1b2c3d4/dependencies \
  -H "Content-Type: application/json" \
  -d '{"dependsOn": "x9y8z7w6"}'

Traverse Dependency Graph

# Downstream dependencies
curl "http://localhost:3000/api/v1/catalog/deps/a1b2c3d4?direction=down"

# Upstream dependents
curl "http://localhost:3000/api/v1/catalog/deps/a1b2c3d4?direction=up"

Create a System

curl -X POST http://localhost:3000/api/v1/catalog/systems \
  -H "Content-Type: application/json" \
  -d '{"name": "billing-system", "description": "All billing-related services"}'

Create an Owner

curl -X POST http://localhost:3000/api/v1/catalog/owners \
  -H "Content-Type: application/json" \
  -d '{"name": "Platform Team", "email": "platform@example.com", "team": "engineering"}'

Response Envelope

All responses follow the standard envelope format:

Success:

{
  "success": true,
  "data": { ... }
}

Error:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Service not found"
  }
}