Routes

Routes define how HTTP traffic reaches your services. Each route maps a domain and path to a service, allowing you to expose your applications to the internet.

Endpoints

Method	Endpoint	Description
GET	/api/routes/	List all your routes
POST	/api/routes/	Create a new route
GET	/api/routes/{id}/	Get route details
PATCH	/api/routes/{id}/	Update a route
DELETE	/api/routes/{id}/	Delete a route

Route Object

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "path": "/api",
  "enabled": true,
  "domain": "domain-uuid",
  "service": "service-uuid",
  "status": "ready",
  "deploy_successful": true,
  "created_at": "2024-10-15T10:00:00Z",
  "updated_at": "2024-10-15T12:00:00Z"
}

Fields

Field	Type	Description
id	UUID	Unique identifier (read-only)
path	string	URL path to match (e.g., /, /api)
enabled	boolean	Whether the route is active
domain	UUID	Domain ID for the route
service	UUID	Service ID to route traffic to
status	string	Current status (read-only)
deploy_successful	boolean	Whether deployment succeeded (read-only)

List Routes

GET /api/routes/

Query Parameters:

• page - Page number for pagination
• project - Filter by project ID

Example:

curl -H "Authorization: Bearer gob_your_key" \
  https://api.example.com/api/routes/

Response:

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "abc123...",
      "path": "/",
      "enabled": true,
      "domain": "domain-uuid",
      "service": "service-uuid",
      "status": "ready"
    }
  ]
}

Create Route

POST /api/routes/

Request Body:

{
  "path": "/api",
  "enabled": true,
  "domain": "domain-uuid",
  "service": "service-uuid"
}

Required Fields:

• path - URL path to match
• domain - ID of a domain you own
• service - ID of a service you own

Optional Fields:

• enabled - Whether route is active (default: true)

Example:

curl -X POST https://api.example.com/api/routes/ \
  -H "Authorization: Bearer gob_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/api",
    "domain": "abc123...",
    "service": "def456..."
  }'

Response (201 Created):

{
  "id": "xyz789...",
  "path": "/api",
  "enabled": true,
  "domain": "abc123...",
  "service": "def456...",
  "status": "pending",
  "deploy_successful": false
}

Get Route

GET /api/routes/{id}/

Example:

curl -H "Authorization: Bearer gob_your_key" \
  https://api.example.com/api/routes/xyz789.../

Update Route

PATCH /api/routes/{id}/

Updatable Fields:

• path - Change the URL path
• enabled - Enable or disable the route
• domain - Change the domain
• service - Change the target service

Example - Disable Route:

curl -X PATCH https://api.example.com/api/routes/xyz789.../ \
  -H "Authorization: Bearer gob_your_key" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

Example - Change Target Service:

curl -X PATCH https://api.example.com/api/routes/xyz789.../ \
  -H "Authorization: Bearer gob_your_key" \
  -H "Content-Type: application/json" \
  -d '{"service": "new-service-uuid"}'

Delete Route

DELETE /api/routes/{id}/

Example:

curl -X DELETE https://api.example.com/api/routes/xyz789.../ \
  -H "Authorization: Bearer gob_your_key"

Response: 204 No Content

Path Patterns

Routes match traffic based on the domain and path combination.

Path	Matches
/	All requests to the domain
/api	Requests to /api and /api/*
/api/v1	Requests to /api/v1 and /api/v1/*

Example Routing

With domain api.example.com:

Route Path	Request URL	Routed To
/	api.example.com/anything	Service A
/api	api.example.com/api/users	Service B
/docs	api.example.com/docs/intro	Service C

Setting Up Routing

Step 1: Create a Domain

First, register your domain:

curl -X POST https://api.example.com/api/domains/ \
  -H "Authorization: Bearer gob_your_key" \
  -H "Content-Type: application/json" \
  -d '{"hostname": "api.myapp.com"}'

Step 2: Create a Route

Then create a route pointing to your service:

curl -X POST https://api.example.com/api/routes/ \
  -H "Authorization: Bearer gob_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/",
    "domain": "domain-id-from-step-1",
    "service": "your-service-id"
  }'

Step 3: Configure DNS

Point your domain's DNS to the Goblins platform. Contact your administrator for the correct DNS settings.

Blue-Green Deployments

Use routes to implement blue-green deployments:

1. Deploy new version as a separate service
2. Test the new service
3. Update the route to point to the new service
4. Delete the old service

# Update route to new service
curl -X PATCH https://api.example.com/api/routes/{id}/ \
  -H "Authorization: Bearer gob_your_key" \
  -H "Content-Type: application/json" \
  -d '{"service": "new-service-uuid"}'

Next Steps

• Domains - Manage your domains
• Services - Manage your services