Gnu Group Learning AcademyGnu Group ↗
Platform Engineering Fundamentals · Module 02 of 12

Developer journeys and platform contracts

Turn developer needs into explicit self-service contracts: inputs, outputs, policies, ownership, failure states, support boundaries and service-level expectations.

Learning objectives

By the end of this module, you should be able to:

  • Map a developer journey and identify avoidable handoffs.
  • Define a platform capability contract with inputs, outputs and failure semantics.
  • Separate platform implementation details from the interface developers depend on.

A platform interface is a contract

A self-service action needs well-defined inputs, resulting resources, policy constraints, ownership, observable status and error messages. Hidden side effects create fragile platforms.

Design the failure path

A golden path must say what happens when policy denies a request, provisioning times out, a dependency is unavailable or rollback is required. Happy-path-only automation simply moves toil to incidents.

Version the interface

Templates, APIs and platform defaults evolve. Consumers need compatibility expectations, deprecation windows and migration guidance so the platform can improve without surprising workloads.

Worked example

Capability contract

{"input":{"service":"orders","tier":"standard"},"output":{"repo":"...","namespace":"..."},"policy":{"owner":"required"},"status":"observable","rollback":"documented"}
  • The contract expresses what the consumer supplies and receives.
  • Policy and rollback are part of the interface, not hidden implementation notes.
Core lab · account-free

Lab 02 — Validate a self-service contract

Goal: Create and validate a small platform request contract.

Before you start

  • No cloud account required.
  • Core lab uses bash/Python 3 and local files only.
STEP 1

Write contract

cat > /tmp/platform-contract.json <<'EOF'
{"inputs":["service_name","owner","environment"],"outputs":["repository","deployment_target","dashboard"],"states":["requested","provisioning","ready","failed"],"rollback":true}
EOF
STEP 2

Validate required semantics

python3 - <<'PY2'
import json
x=json.load(open('/tmp/platform-contract.json'))
assert {'service_name','owner','environment'}<=set(x['inputs'])
assert {'repository','deployment_target','dashboard'}<=set(x['outputs'])
assert {'ready','failed'}<=set(x['states'])
assert x['rollback'] is True
print('platform contract valid')
PY2
STEP 3

Describe one failure

Write the developer-visible error and support path for a denied or failed request.

Verify

  • Required input/output/status fields are present.
  • The contract includes a failure and rollback model.

Expected outcome

  • A machine-checkable self-service contract.

Diagnose / troubleshoot

  • If the contract names internal implementation classes, ask whether developers truly need to depend on them.
  • If “failed” has no diagnostic evidence, add correlation/status information.
Real-world connection

Stable contracts let platform teams change implementation behind the interface without breaking consumers.

Real-tool practicum · optional but recommended

Optional tool lab — API-first self-service

Sketch an OpenAPI or JSON Schema contract for the same capability.

Prerequisites

  • Use a disposable local lab or organization-approved sandbox.
  • Pin tool versions in real platform automation; do not blindly depend on latest.

Cost / risk

  • Core learning is account-free. Optional external/sandbox tools may consume local CPU/RAM; do not use production credentials or billable cloud resources.

Warnings

  • Do not point training automation at production clusters, repositories or cloud accounts.
  • A successful command is not proof of a good platform interface; validate the developer outcome and guardrails.
TOOL 1
python3 -m json.tool /tmp/platform-contract.json
Avoid these traps

Common mistakes

  • Designing only the UI and not the contract.
  • Returning “failed” without actionable evidence.
  • Changing defaults without versioning or migration communication.
Knowledge check

Can you connect the developer need to a platform contract?

Three concept checks plus one scenario check.

1What belongs in a platform contract?

Inputs, outputs, policies, ownership, observable states, errors and lifecycle expectations.

2Why design failure states explicitly?

Self-service remains usable when dependencies fail or policy denies a request.

3Why version platform interfaces?

Consumers need predictable compatibility and migration behavior as the platform evolves.

4Scenario: a template silently changes the default database class and production costs double. What platform practice was missing?

Versioned/default-change governance with observable impact and migration communication.

My Learning

Record your progress for this module.

Progress is saved in this browser immediately. When you sign in to My Learning, it can also sync across devices.

Not started

Attempt the core lab and knowledge checks before marking the module complete.