Example build / Stockroom API
A backend another application can depend on
The result has a documented contract and predictable failures. A list of endpoints without validation, tests, or runtime configuration is not a finished API.
Keep product and movement records persistent by choosing how to add a managed database to the API.
/products
List and filter products.
/movements
Validate and record stock changes.
/inventory
Return current calculated stock.
/health
Report process health without private data.
Before you prompt
Write the contract before generating handlers
Start with the consumers and resources. That gives the AI a reason for every route, field, status code, and permission instead of producing a generic CRUD surface.
Known consumer
Name the web app, mobile app, internal tool, or partner that will call the API.
Resource ownership
State whether records are public, user-owned, team-owned, or service-owned.
Failure contract
Choose one safe JSON error shape and meaningful response codes before implementation.
Runtime evidence
Keep start, port, health, database, secret, migration, and smoke-test requirements together.
If you need to compare stacks before prompting, review the API deployment guides.
Design the contract
Ask for routes, data, permissions, and tests before code
This prompt makes the agent inspect the existing stack and show the API contract first. Replace the bracketed values and review the response as the API's working brief.
Help me plan a production-shaped REST API in this Adios workspace. Do not edit files yet.
The API:
- Name: [API NAME]
- Consumer: [WEB APP, MOBILE APP, INTERNAL TOOL, OR PARTNER]
- Core resource: [RESOURCE]
- Main actions: [CREATE, LIST, READ, UPDATE, OR OTHER ACTIONS]
- Authentication: [NONE FOR A PUBLIC DEMO, USER TOKEN, OR SERVICE API KEY]
- Database: [CURRENT PROJECT DATABASE OR POSTGRES]
Before proposing changes, inspect the repository, current framework, package manager, tests, health route, environment configuration, and adios.yaml.
Return:
1. the route table with methods and response codes;
2. request and response shapes;
3. validation and error behavior;
4. the data model and migration approach;
5. authentication and authorization boundaries;
6. rate-limit or abuse considerations;
7. automated tests and manual curl examples; and
8. the Adios runtime, health, database, and secret configuration required.
Prefer the existing stack. Explain any new dependency. Wait for my approval before editing.What a useful response contains
- A route table rather than a feature wish list
- Request, response, validation, and error shapes
- A named ownership and authorization model
- Runtime and test requirements before edits
Implement the contract
Build the API without replacing the working stack
After approving the contract, use this prompt to implement it with consistent errors, parameterized data access, tests, and runnable examples.
Build the REST API from the plan I approved.
Requirements:
- Keep the existing language, framework, package manager, and Adios deployment files.
- Preserve a lightweight unauthenticated health endpoint that does not expose private data.
- Validate every external input and return one consistent JSON error shape.
- Enforce authentication and authorization on the server when the plan requires them.
- Use parameterized database access through the project's established data layer.
- Add reversible migrations if this repository uses migrations.
- Never hard-code credentials. Refer to database and authentication values by environment-variable name.
- Add concise API documentation and runnable example requests.
- Add tests for the happy path, invalid input, missing records, unauthorized access, and one database failure path that can be tested safely.
- Run the formatter, linter, tests, and production build or compile command already used by the project.
When finished, give me the route table, changed files, test results, required Adios configuration, and exact commands I can run against Preview. Do not deploy to production.What a useful response contains
- Handlers that match the approved route table
- Consistent validation and error behavior
- Tests for success, failure, and access control
- Copyable Preview requests
Attack the assumptions
Test malformed input, access boundaries, and repeat requests
A happy-path request proves little. This review prompt checks the contract from the perspective of an unknown or unreliable client.
Review this API as if an unknown client will call it. Fix only verified issues and do not deploy.
Check:
- routes use the intended HTTP methods and status codes;
- malformed, missing, oversized, and unexpected inputs fail safely;
- authentication cannot be bypassed and one caller cannot access another caller's protected data;
- error responses do not expose stack traces, secrets, database details, or internal paths;
- repeated requests behave safely where idempotency is required;
- database writes and migrations are consistent;
- API documentation and example requests match the implementation;
- health checks remain lightweight;
- logs are useful without recording credentials or sensitive request bodies; and
- all formatter, lint, test, and compile or build checks pass.
Return a table of checks and evidence, the exact Preview requests I should run, and any remaining risk.What a useful response contains
- Negative tests, not only 200 responses
- No internal details in public errors
- Documentation checked against implementation
- An explicit remaining-risk list
Match source to runtime
Compare the API contract with the Adios release contract
The final prompt checks that the source, migration, start command, port, health path, dependencies, secrets, and smoke tests describe the same release.
Prepare this API for an Adios deployment review. Do not deploy until I approve it.
Confirm the start command, listening host and port, health path, required environment-variable names, database dependency, migration command, and expected public route. Compare them with adios.yaml and report any mismatch.
Then give me:
1. the final automated-check results;
2. five safe smoke-test requests for the Preview URL;
3. one rollback or recovery note for a failed migration;
4. the secrets I must configure through Adios rather than source; and
5. a post-deployment check covering health, logs, authentication, and one write/read cycle.
Stop for my approval before production deployment.What a useful response contains
- No mismatch between process and adios.yaml
- Safe Preview and production smoke tests
- A migration recovery note
- An explicit pause before deploy
Test the result
A passing build is the start of the review
Open Preview and perform the important journeys yourself. Ask the agent for evidence, but do not confuse its summary with your approval.
Contract
- Every documented route, method, status code, and field matches the implementation.
- Malformed and unexpected input returns the same safe JSON error shape.
- Pagination, filtering, and ordering behave predictably where present.
Trust boundary
- Missing, invalid, expired, and wrong-owner credentials fail safely.
- A public error contains no stack trace, secret, SQL detail, or internal path.
- Logs omit credentials and unnecessary sensitive request bodies.
Runtime
- The process listens on the declared host and port.
- Migrations, health, formatter, lint, tests, and build or compile checks pass.
- One write/read smoke test succeeds against Preview and after release.
Human approval gate
Release the API contract and its evidence together
Treat the route table, migrations, environment-variable names, health path, logs, and smoke requests as part of the release. Approve only when they match the version running in Preview.
host and deploy the finished AI-built API- 01Run the safe Preview requests and compare them with the documentation.
- 02Confirm database migration and recovery instructions for this version.
- 03Configure named secrets in Adios and keep their values out of source.
- 04Verify start, port, health, and dependency settings in adios.yaml.
- 05Approve the release, then repeat health, authentication, and one write/read cycle.
Questions before you start
What this guide does—and does not—promise
Does this guide build an AI API or build my API with AI?
It uses the Adios AI agent to build your application's backend. The example API manages stockroom data; it does not call a language model or expose an AI model API.
Which backend framework should I use?
Prefer the framework already used by the repository. If you are starting fresh, choose a stack your team can maintain and that has clear validation, testing, migration, and runtime conventions. The prompt asks the agent to explain any new dependency.
Should an API health endpoint require authentication?
A process health endpoint is usually lightweight and unauthenticated so the platform can check it, but it must not expose secrets, private records, dependency credentials, or diagnostic internals.
How do I know an AI-generated API is safe to deploy?
Do not rely on generation alone. Review the contract, run positive and negative tests, verify authorization and errors, inspect secret handling, apply migrations safely, test Preview, and approve the exact release candidate yourself.