ProvableHQ / ProvableHQ/snarkOS
[Proposal] Standardize REST API endpoints
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 4.5k
- Forks
- 2.7k
- Avg merge
- 2d 59m
- Merged PRs (30d)
- 29
Description
The current API implementation doesn't follow common REST conventions, and part of its implementation makes it more difficult to implement clients for it (for example the use body in the GET requests).
Summary of suggested changes:
- don't use request body for GET requests (not all clients support this, e.g. the browser fetch doesn't). instead use the path vars for identifiers, querystring args for other parameters or http headers for sensitive information.
- add explicit api versioning (separate from testnet namespace),
- use nouns instead of verbs
- use plural for all entities
- don't use uris to fetch a specific attribute like height
- use querystrings to filter lists elements or fields within an object
Suggested endpoint changes:
GET /testnet3/block/{height} -> /api/v1/testnet3/blocks/{height}
GET /testnet3/latest/block -> /api/v1/testnet3/blocks/latest. alternatively, GET /api/v1/testnet3/blocks could return a list sorted by most recent
GET /testnet3/latest/height -> remove in favor of block attribute. if we want to fetch height only it can be /api/v1/testnet3/blocks/latest?fields=height
GET /testnet3/latest/hash -> remove in favor of block attribute. if we want to fetch height only it can be /api/v1/testnet3/blocks/latest?fields=hash
GET /testnet3/statePath/{commitment} -> /api/v1/testnet3/state-paths/{commitment}
GET /testnet3/records/all {JSON body} -> /api/v1/testnet3/records {view key in HTTP header}
GET /testnet3/records/spent {JSON body} -> /api/v1/testnet3/records?spent=true {view key in HTTP header}
GET /testnet3/records/unspent {JSON body} -> /api/v1/testnet3/records?spent=false {view key in HTTP header}
GET /testnet3/peers/count -> remove in favor of getting peer list, potentially with a total count if number is large
GET /testnet3/peers/all -> /api/v1/testnet3/peers
GET /testnet3/transactions/{height} -> /api/v1/testnet3/transactions/{height}
GET /testnet3/transaction/{id} -> /api/v1/testnet3/transactions/{id}
POST /testnet3/transaction/broadcast -> POST /api/v1/testnet3/transaction
POST /testnet3/program/deploy -> /api/v1/testnet3/programs/deployment
POST /testnet3/program/execute -> /api/v1/testnet3/programs/execution
GET /testnet3/program/program_id -> GET /api/v1/testnet3/programs/{id}
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by locating the current REST API route definitions and comparing them with the proposed endpoint mapping in this issue. Define the API versioning, resource naming, query and header conventions, then verify that all listed endpoints follow the agreed design and that existing client behavior is addressed.
Written by the indexing model from the issue text.
Assessment
- Domain
- api, backend-api-design
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 20/100