Services

Services are containerized applications deployed to the Goblins platform. Each service runs your Docker image with configurable replicas, port settings, and attached configuration.

Endpoints

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

Service Object

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "my-api",
  "image": "myregistry/my-api:v1.0.0",
  "port": 8080,
  "replicas_target": 3,
  "replicas_running": 3,
  "status": "ready",
  "config": "config-uuid",
  "secret": "secret-uuid",
  "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)
name	string	Service name (max 32 characters, unique per account)
image	string	Docker image to deploy (e.g., nginx:1.25)
port	integer	Port your application listens on (1-65535)
replicas_target	integer	Desired number of instances (1-12)
replicas_running	integer	Currently running instances (read-only)
status	string	Current status (read-only)
config	UUID	Configuration to attach
secret	UUID	Secret to attach
deploy_successful	boolean	Whether last deployment succeeded (read-only)

Status Values

Status	Meaning
not ready	Service created but not yet deployed
pending	Deployment in progress
ready	Service is running and healthy
error	Deployment failed
updating	Update in progress

List Services

GET /api/services/

Query Parameters:

• page - Page number for pagination
• ordering - Sort field (name, -created_at, etc.)
• project - Filter by project ID

Example:

curl -H "Authorization: Bearer gob_your_key" \
  "https://api.example.com/api/services/?ordering=-created_at"

Response:

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "web-api",
      "image": "myorg/api:v1.2.0",
      "port": 8000,
      "replicas_target": 3,
      "replicas_running": 3,
      "status": "ready"
    }
  ]
}

Create Service

POST /api/services/

Request Body:

{
  "name": "my-service",
  "image": "nginx:1.25",
  "port": 80,
  "replicas_target": 2,
  "config": "config-uuid",
  "secret": "secret-uuid"
}

Required Fields:

• name - Unique name (letters, numbers, hyphens only)
• image - Docker image to deploy
• port - Port number (1-65535)
• config - ID of a configuration you own
• secret - ID of a secret you own

Optional Fields:

• replicas_target - Number of instances (default: 1, max: 12)

Example:

curl -X POST https://api.example.com/api/services/ \
  -H "Authorization: Bearer gob_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-api",
    "image": "myregistry/my-api:v1.0.0",
    "port": 8080,
    "replicas_target": 2,
    "config": "7a6b5c4d-...",
    "secret": "8b7c6d5e-..."
  }'

Response (201 Created):

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "my-api",
  "image": "myregistry/my-api:v1.0.0",
  "port": 8080,
  "replicas_target": 2,
  "replicas_running": 0,
  "status": "pending",
  "deploy_successful": false
}

Get Service

GET /api/services/{id}/

Example:

curl -H "Authorization: Bearer gob_your_key" \
  https://api.example.com/api/services/123e4567.../

Returns the full service object.

Update Service

PATCH /api/services/{id}/

Updatable Fields:

• image - Deploy a new version
• port - Change the port
• replicas_target - Scale up or down

Example - Update Image:

curl -X PATCH https://api.example.com/api/services/123e4567.../ \
  -H "Authorization: Bearer gob_your_key" \
  -H "Content-Type: application/json" \
  -d '{"image": "myregistry/my-api:v1.1.0"}'

Example - Scale Service:

curl -X PATCH https://api.example.com/api/services/123e4567.../ \
  -H "Authorization: Bearer gob_your_key" \
  -H "Content-Type: application/json" \
  -d '{"replicas_target": 5}'

Deployment Tracking

Each update creates a deployment record. View deployment history to see all changes and roll back if needed.

Delete Service

DELETE /api/services/{id}/

Example:

curl -X DELETE https://api.example.com/api/services/123e4567.../ \
  -H "Authorization: Bearer gob_your_key"

Response: 204 No Content

Deletion Protection

You cannot delete a service that has routes pointing to it. Delete the routes first.

Quotas

Your account has limits on services and replicas:

Service Quota Exceeded (400):

{
  "error": "Service quota exceeded. Maximum 10 services allowed.",
  "quota": {
    "current": 10,
    "max": 10
  }
}

Replica Quota Exceeded (400):

{
  "error": "Replica quota exceeded. Maximum 50 total replicas allowed.",
  "quota": {
    "current": 48,
    "max": 50,
    "requested": 3
  }
}

View Deployments

Get deployment history for a service:

GET /api/services/{id}/deployments/

See Deployments for details on viewing history and rolling back.

Validation Errors

Duplicate Name:

{
  "error": "A service with the name 'my-service' already exists"
}

Invalid Image:

{
  "image": ["Enter a valid Docker image name"]
}

Invalid Port:

{
  "port": ["Ensure this value is between 1 and 65535"]
}

Best Practices

Use Specific Image Tags

Always use specific version tags instead of latest:

{
  "image": "myregistry/my-api:v1.2.3"
}

This ensures reliable deployments and rollbacks.

Start Small

Begin with 1-2 replicas and scale up as needed:

{
  "replicas_target": 2
}

Monitor Deployment Status

After creating or updating a service, poll for deployment status:

# Check service status
curl -H "Authorization: Bearer gob_your_key" \
  https://api.example.com/api/services/123e4567.../

Wait for status to change from pending to ready.

Complete Example

Deploy a new service and set up routing:

# 1. Get your default config and secret IDs
CONFIG_ID=$(curl -s -H "Authorization: Bearer $API_KEY" \
  https://api.example.com/api/configs/ | jq -r '.results[0].id')

SECRET_ID=$(curl -s -H "Authorization: Bearer $API_KEY" \
  https://api.example.com/api/secrets/ | jq -r '.results[0].id')

# 2. Create the service
SERVICE=$(curl -s -X POST https://api.example.com/api/services/ \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-api",
    "image": "myregistry/my-api:v1.0.0",
    "port": 8080,
    "replicas_target": 2,
    "config": "'$CONFIG_ID'",
    "secret": "'$SECRET_ID'"
  }')

echo "Service created: $(echo $SERVICE | jq -r '.id')"

Next Steps

• Routes - Expose your service to the internet
• Deployments - View history and rollback
• Configs - Manage service configuration
• Secrets - Manage sensitive data