When you build a platform, you are building a product. The interface to that product — whether it's a YAML file, a CLI command, or a web form — is an API. Your internal developers are your customers, and their experience using that API determines whether the platform succeeds or gets abandoned.
A common mistake is to expose the raw APIs of the underlying tools directly. This is the equivalent of a car manufacturer removing the steering wheel and giving you direct access to the steering rack. Technically complete. Practically unusable.
Focus on Intent
Good platform APIs are designed around the developer's intent, not the underlying implementation.
The developer's intent is: "I want a PostgreSQL database for my payments service, and it needs to be highly available."
The implementation is: create an RDS parameter group, configure a multi-AZ deployment, set up automated backups with a 7-day retention window, create a Secrets Manager secret with rotation enabled, configure a security group allowing access only from the application's subnet, tag all resources with the correct cost center, and register the connection string in the service's configuration store.
The developer should express the intent. The platform should handle the implementation.
Bad API (Implementation-focused):
# Forces the developer to be an AWS infrastructure expert
resources:
- type: aws_db_instance
engine: postgres
engine_version: "14.7"
instance_class: db.t3.medium
multi_az: true
allocated_storage: 20
db_subnet_group_name: "prod-subnet-group-abc123"
vpc_security_group_ids:
- "sg-0a1b2c3d4e5f"
backup_retention_period: 7
storage_encrypted: true
kms_key_id: "arn:aws:kms:us-east-1:123456789:key/abc-def"
Good API (Intent-focused):
# The developer expresses what they need. The platform decides how.
name: payments-service
dependencies:
database:
type: postgres
tier: standard # platform maps this to an appropriate instance size
ha: true # platform handles multi-AZ, backups, failover
The platform takes the high-level intent and translates it into the dozens of low-level infrastructure steps required to make it happen — correctly, securely, and consistently every time.
The Principle of Progressive Disclosure
A well-designed platform API applies progressive disclosure: the simple case is simple, and the complex case is possible.
The ha: true field in the good API above has a sensible default (the platform's standard HA configuration). But a developer with a genuine need can override specifics:
dependencies:
database:
type: postgres
tier: standard
ha: true
# Advanced overrides — only when you genuinely need them
backup_retention_days: 30 # override the default of 7
maintenance_window: "sun:03:00-sun:04:00"
The escape hatch exists. It's just not required for the common case. This is the same principle as a car's automatic transmission: it handles gear selection for you by default, but a manual mode exists for drivers who need it.