A Developer Portal Is Only the Entrance: Design a Self-Service Contract

A developer opens an internal portal, fills out a form and receives a ticket number. The interface looks modern, but another engineer still has to interpret the request, choose the configuration, create the resource and explain how to use it. The team has improved the entrance to a process. Whether it has created useful self-service depends on what happens after the click.

The CNCF community's September discussion of platform interface maturity makes the difference between standardized tooling and greater user autonomy a central concern. For a candidate, that suggests a concrete portfolio question: can another developer complete one meaningful task through your system, including an ordinary failure, without you acting as the hidden operator? The project below is an original design exercise for answering that question.

Select one recurring request

Choose a narrow capability, such as creating a temporary preview environment for a small sample service. Define the person requesting it, the reason they need it and what successful completion looks like. Avoid beginning with a catalog of unrelated cloud services. One carefully bounded journey will expose more useful design decisions than a dozen forms connected to scripts that only their author understands.

Use a disposable local environment if you do not already have a suitable development account. A preview can be a process, a container or a small isolated deployment. The exact infrastructure matters less than the contract you expose and the behavior you verify. Explain the project's scale and limits. A local demonstration can show interface design and recovery without pretending to prove organization-wide adoption or cloud-scale reliability.

Write the contract before the form

Describe the inputs in plain language. A request might include a source revision, an environment name and a lifetime chosen from a small supported set. Define the allowed values, defaults and validation errors. Include the resulting resource identity, current state, owner and expiry time in the response. A person should know what the request means before learning the implementation details of your orchestrator.

Specify what the capability deliberately does not accept. Arbitrary shell commands, unbounded resource sizes and uncontrolled network destinations are poor defaults for this exercise. Where a legitimate exception exists, describe a review route. The aim is to make routine work predictable while making exceptional work visible. Silently accepting an input that the implementation cannot safely honor creates more support work than a clear, actionable rejection.

Treat ownership as part of the interface

Give every created resource an owner and a purpose. Decide who can inspect it, renew it or remove it. In the demonstration, use synthetic identities and a simple permission model that is easy to audit. Show at least one denied request, such as a second user trying to delete an environment they do not own. A successful deployment is only one part of the user journey.

Also explain who owns the capability itself. If provisioning fails, someone needs to know whether to retry, fix their input or seek help. Put a support route and a useful error code in the result. Do not expose secret values or internal stack traces to make the error appear technical. Preserve the diagnostic detail for the appropriate operator while giving the requester enough information to choose a next step.

Make progress inspectable

A long-running action needs a durable identity. Return that identity and let the requester inspect the state rather than keeping a browser spinner alive indefinitely. For the exercise, define a small state model: requested, validating, creating, ready, failed and deleting. Describe which transitions are legal and what a repeated request should do. Your implementation can be modest as long as its promises are explicit.

Test what happens when the client disconnects after submitting a request. The user should be able to find the original operation instead of creating another environment by accident. Use a stable idempotency key or an equivalent documented mechanism, and verify that the same operation is not executed twice. This makes a useful interview demonstration because it connects an interface decision to resource ownership and operational consequences.

Design the failure journey

Introduce a controlled failure after validation but before the resource is ready. Record whether the action created anything, whether cleanup is required and whether retrying is safe. The requester should see a meaningful result. The operator should have enough context to inspect the failure. Avoid a design in which every unsuccessful operation appears identical while leaving an unknown amount of infrastructure behind it.

Try a second failure during cleanup. A partially removed environment needs a visible state and a bounded recovery procedure. Do not describe deletion as complete merely because a button was pressed. Record the resource identity and the cleanup result, then make the remaining work observable. These cases help distinguish a supported capability from a thin wrapper around a command that behaves well only on its first successful run.

Build an expiry policy into the example

Temporary environments should have a defined end. In this proposed project, each environment has an explicit lifetime and can be renewed within a documented limit. Show the expiry in the interface and explain how cleanup is triggered. Use a short synthetic lifetime in tests so the behavior can be reviewed without waiting for a real workweek. Clearly separate that test setting from any recommended operational policy.

Define what happens to data before adding automated deletion. A preview containing generated fixtures can often be recreated. A user-uploaded document may require a different lifecycle. Keep this project limited to disposable data, and record that boundary in the contract. A convincing platform design makes resource policy understandable to its users; it does not hide consequential decisions behind an attractive countdown badge.

Measure a completed task

The CNCF platform engineering maturity model considers investment, adoption, interfaces, operations and measurement separately. It also cautions that greater maturity requires resources and should fit an organization's context. Use that perspective to avoid making the largest possible platform your portfolio goal. Demonstrate one capability whose usefulness you can inspect and whose maintenance responsibilities you understand.

For your exercise, record time to a usable preview, the number of manual interventions and the outcome of each test case. Include failed attempts in the report. If a friend tries the interface, say that the sample is one participant, describe their environment and keep their feedback separate from timing measurements. A tiny usability observation can improve the project without becoming a statistically credible claim about developer productivity.

Show the maintenance path

A supported interface needs a way to change. Introduce a second version of the preview template and explain how existing environments behave. Does the change apply only to new requests? Can an old environment be recreated? What happens if the template stops supporting an input? Include a compatibility note and one test protecting an existing supported request. This is where the project's long-term ownership becomes visible.

Keep implementation details behind a clear boundary. Users should not have to discover a container identifier to renew an environment if the public contract promises renewal by environment name. Operators may need that identifier for diagnosis. Document both views and how they connect. A stable external identity allows implementation changes without requiring every user to learn the next orchestration tool.

Avoid a dashboard full of empty promises

A portfolio portal does not need to advertise capabilities that have no working implementation. Show the narrow service clearly, with a real operation history from the demonstration. Explain unavailable features as future work in the README. The most valuable screenshot may be a failed request with a comprehensible recovery action, especially when the accompanying test proves that the recovery does what the interface says.

Similarly, do not put credentials into a demonstration to make it look realistic. Use restricted development identities, synthetic data and sanitized logs. Describe the permission boundary and how an operator would rotate a compromised credential in a real deployment. You can demonstrate thoughtful security decisions without claiming a complete enterprise identity architecture. The scope should be obvious to a reviewer before they run anything.

Use the artifact in a job search

Inspect platform engineering vacancies and compare the responsibilities rather than just the title. One team may need deployment infrastructure, another a developer experience product, and another deep expertise in a particular runtime. Connect your project to a specific responsibility you can demonstrate. Check the original listing for location, seniority and required experience; a search result is a starting point for that verification.

For a platform role, explain the contract, recovery and ownership model. For a backend role, explain request identity and state transitions. For a product role, discuss which user problem you selected and what feedback changed. For QA, show the lifecycle and permission tests. The same small service can support different conversations when you are precise about the part of the work you performed.

What a reviewer should be able to do

A useful completion test is straightforward: a reviewer can create a disposable preview, see its progress, retry safely after a simulated disconnect, understand a deliberate failure and observe cleanup. They can inspect the contract and find the tests that protect it. They can also identify what your local demonstration does not establish, including scale, availability and organizational adoption. Keep those limitations next to the results.

Your final walkthrough should answer one question: which recurring dependency on a human operator did the capability remove, and what responsibility remains? That explanation gives the interface a purpose. It also creates a better foundation for a platform engineering interview than a tour of tools, because the discussion can move from the visible screen to the decisions that make the service dependable.

Sources and scope

• CNCF community article: Platform engineering maturity, September 1, 2026. Context for standardized interfaces and self-service; its anecdotal percentages are not used as benchmarks here.
• CNCF Platform Engineering Maturity Model. The independent assessment dimensions and the importance of organizational context.
• The preview service, state model, tests and measurement plan are original ApplyDjinn proposals. Illustrations describe the proposed design and do not report a production deployment or hiring survey.