aws / aws/res

API documentation

Open
#174 2 comments 2 reactions 0 assignees View on GitHub
enhancement
Dominant language
Python
Stars
115
Forks
35
PR merge metrics
No merged PRs in 30d

Description

We're building backend automation around RES and there's no documented, supported, stable REST API we can safely call from our own services. RES clearly has a capable API surface (the web portal uses it), but it isn't published or covered by any compatibility guarantee, so any automation we write against it is effectively built on an internal contract that can change between releases.
Concretely, we run a desired-state control plane that needs to manage RES projects programmatically — for example, assigning a per-project budget (enable_budgets + budget.budget_name) so RES enforces VDI spend — across a large and growing number of projects. Doing this by hand in the Admin portal doesn't scale, and our only programmatic option today is the undocumented internal namespace the portal happens to use. I'm always frustrated when the only way to automate RES is to reverse-engineer an internal API and re-verify it on every upgrade.

**Describe the solution you'd like**

A documented and maintained REST API for RES that external backends can call to automate common administrative operations — authenticated with standard RES credentials, versioned, idempotent, and covered by a published backward-compatibility policy. At minimum it should cover project lifecycle and configuration
(create/update/read/list projects, including budget association and other project settings), with clear request/response schemas in the docs The key requirement is that it's a supported contract we can depend on, not an internal endpoint that may change without notice.

**Describe alternatives you've considered**

- Admin portal (manual): doesn't scale, error-prone, no GitOps/audit trail.
- Calling the internal API the portal uses: functionally works but is undocumented/unsupported — no compatibility guarantee, requires re-verification each RES release.
- Writing RES's DynamoDB tables directly: rejected — bypasses RES's own validation and is even more fragile.
- Doing everything outside RES (e.g. enforcing budgets via AWS-native controls): possible for some cases but loses RES's native behaviour and doesn't cover general project automation.

Contributor guide

Open the contributing guide

Research direction

The payload identifies no implementation files, tests, or entry points. Start by locating the internal API namespace used by the web portal and its project-management operations, then compare them with the requested external contract. Done means supported, authenticated project CRUD and budget settings with documented schemas, versioning, idempotency, and a backward-compatibility policy.

Written by the indexing model from the issue text.

Assessment

Tech stack
aws, python
Domain
api, backend, cloud
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.