Goblins

Appearance

Domains ​

Domains represent the hostnames used in your routes. Register a domain before creating routes that use it.

Endpoints ​

MethodEndpointDescription
GET/api/domains/List all your domains
POST/api/domains/Register a new domain
GET/api/domains/{id}/Get domain details
PATCH/api/domains/{id}/Update a domain
DELETE/api/domains/{id}/Delete a domain

Domain Object ​

json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "hostname": "api.example.com",
  "created_at": "2024-10-15T10:00:00Z"
}

Fields ​

FieldTypeDescription
idUUIDUnique identifier (read-only)
hostnamestringDomain hostname
created_atdatetimeWhen the domain was registered (read-only)

List Domains ​

http
GET /api/domains/

Example:

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

Response:

json
{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "abc123...",
      "hostname": "api.example.com",
      "created_at": "2024-10-15T10:00:00Z"
    },
    {
      "id": "def456...",
      "hostname": "app.example.com",
      "created_at": "2024-10-16T14:00:00Z"
    }
  ]
}

Create Domain ​

http
POST /api/domains/

Request Body:

json
{
  "hostname": "api.example.com"
}

Required Fields:

  • hostname - The domain hostname

Example:

bash
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"}'

Response (201 Created):

json
{
  "id": "xyz789...",
  "hostname": "api.myapp.com",
  "created_at": "2024-10-17T09:00:00Z"
}

Get Domain ​

http
GET /api/domains/{id}/

Example:

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

Update Domain ​

http
PATCH /api/domains/{id}/

Updatable Fields:

  • hostname - Change the hostname

Example:

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

Delete Domain ​

http
DELETE /api/domains/{id}/

Example:

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

Response: 204 No Content

Deletion Protection

You cannot delete a domain that has routes using it. Delete the routes first.

json
{
  "error": "Cannot delete domain: it is referenced by one or more existing routes"
}

DNS Configuration ​

After registering a domain in Goblins, you need to configure your DNS to point to the platform.

Getting DNS Settings ​

Contact your Goblins administrator for:

  • The IP address or CNAME to point your domain to
  • Any required DNS records (TXT, etc.) for verification

Common DNS Configurations ​

A Record:

api.example.com.  A  <goblins-ip-address>

CNAME Record:

api.example.com.  CNAME  goblins.yourplatform.com.

Workflow ​

1. Register Domain ​

bash
DOMAIN=$(curl -s -X POST https://api.example.com/api/domains/ \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hostname": "api.myapp.com"}')

DOMAIN_ID=$(echo $DOMAIN | jq -r '.id')

2. Configure DNS ​

Update your DNS provider to point to Goblins.

3. Create Routes ​

bash
curl -X POST https://api.example.com/api/routes/ \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/",
    "domain": "'$DOMAIN_ID'",
    "service": "your-service-id"
  }'

Next Steps ​

  • Routes - Create routes using your domains
  • Services - Services to route traffic to

Goblins Platform Documentation