ProvableHQ / ProvableHQ/snarkOS

[Proposal] Standardize REST API endpoints

Open
#2,002 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

design help-wanted refactor
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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.