Skip to content

Instantly share code, notes, and snippets.

@hennevogel
Last active August 28, 2018 09:42
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
Star You must be signed in to star a gist
Save hennevogel/9a31ad717f8d3dee07c66c2b1b00edcf to your computer and use it in GitHub Desktop.
Status API Design

For simplicity I have abbreviated $BUCKET. For instance a Repository get's published a lot of times so it has many $BUCKETs (called Status::RepositoryPublished currently). Checks for a certain Package commit would need the same pattern. On the other hand a BsRequest only get's created once, so it is the $BUCKET.

Use existing routing...

This is how we are currently would do it. We have some special $BUCKET called _status.

Repository

  • GET /build/:project_name/:repository_name/_status -> Status::Checks for latest $BUCKET for Repository
  • GET /build/:project_name/:repository_name/_status/:bucket_id -> List Status::Checks for $BUCKET
  • PUT /build/:project_name/:repository_name/_status/:bucket_id -> Create Status::Checks for $BUCKET
  • GET/PUT/DELETE /build/:project_name/:repository_name/_status/:bucket_id/:check_id -> Read/Update/Destroy Status::Check inside $BUCKET

Package

  • GET /build/:project/:package/_status/ -> List Status::Checks for latest $BUCKET for Package
  • GET /build/:project_name/:package_name/_status/:bucket_id -> List Status::Checks for $BUCKET
  • PUT /build/:project_name/:package_name/_status/:bucket_id -> Create Status::Checks for $BUCKET
  • GET/PUT/DELETE /build/:project_name/:package_name/_status/:bucket_id/:check_id -> Read/Update/Destroy Status::Check inside $BUCKET

Request

  • GET /request/:request_id/_status -> Status::Checkss for this BsRequest
  • PUT /request/:request_id/_status -> Create Status::Checks for BsRequest
  • GET/PUT/DELETE /request/:request_id/_status/:check_id -> Read/Update/Destroy Status::Check inside BsRequest

Package Commit

  • GET /source/:project_name/:package_name/_status -> Status::Checks for latest $BUCKET for Package
  • GET /source/:project_name/:package_name/_status/:bucket_id -> List Status::Checks for $BUCKET
  • PUT /source/:project_name/:package_name/_status/:bucket_id -> Create Status::Checks for $BUCKET
  • GET/PUT/DELETE /source/:project_name/:package_name/_status/:bucket_id/:check_id -> Read/Update/Destroy Status::Check inside $BUCKET

Project Commits(???)

  • GET /source/:project_name/_status -> List Status::Checks for Project
  • PUT /source/:project_name/_status -> Create Status::Checks for Project
  • GET/PUT/DELETE /source/:project_name/_status/:check_id -> Read/Update/Destroy Status::Check inside Project

PROS

No new prefixes

CONS

As soon as you have 2 things below a prefix you have clashes like:

  • Can't have an Architecture called _status because the route /build/:project/:repository/:arch exists
  • Can't have an Package called _status because the route /source/:project/:package exists (a leading _ is already forbidden in package names)
  • Can't have a file in a Package called _status because The route /build/:project/:package/:filename exists
  • Can't have a Package.where(name: 'hans') and a Repository.where(name: 'hans'). Because both /build/:project/:package/_status/ and /build/:project/:repository/_status/ exist

...or Resourceful routing

Repository

  • GET /projects/:project_name/repositories/:repository_name/$BUCKET -> List all $BUCKETs for Repository
  • GET /projects/:project_name/repositories/:repository_name/$BUCKET?latest=true -> Latest $BUCKET for Repository
  • GET /projects/:project_name/repositories/:repository_name/$BUCKET/:bucket_id -> List Status::Checks for $BUCKET
  • PUT /projects/:project_name/repositories/:repository_name/$BUCKET/:bucket_id -> Create Status::Checks for $BUCKET
  • GET/PUT/DELETE /projects/:project_name/repositories/:repository_name/$BUCKET/:bucket_id/:check_id -> Read/Update/Destroy Status::Check inside $BUCKET

Project

  • GET /projects/:project_name/$BUCKET -> List all $BUCKETs for Project
  • GET /projects/:project_name/$BUCKET?latest=true -> Latest $BUCKET for Project
  • GET /projects/:project_name/$BUCKET/:bucket_id -> List Status::Checks for $BUCKET
  • PUT /projects/:project_name/$BUCKET/:bucket_id -> Create Status::Checks for $BUCKET
  • GET/PUT/DELETE /projects/:project_name/$BUCKET/:bucket_id/:check_id -> Read/Update/Destroy Status::Check inside $BUCKET

Package

  • GET /projects/:project_name/packages/:package_name/$BUCKET -> List all $BUCKETs for Repository
  • GET /projects/:project_name/packages/:package_name/$BUCKET?latest=true -> Latest $BUCKET for Repository
  • GET /projects/:project_name/packages/:package_name/$BUCKET/:bucket_id -> List Status::Checks for $BUCKET
  • PUT /projects/:project_name/packages/:package_name/$BUCKET/:bucket_id -> Create Status::Checks for $BUCKET
  • GET/PUT/DELETE /projects/:project_name/packages/:package_name/$BUCKET/:bucket_id/:check_id -> Read/Update/Destroy Status::Check inside $BUCKET

Request

  • GET /requests/:request_number/$BUCKET -> List Status::Checks for BsRequest
  • PUT /requests/:request_number/$BUCKET -> Create Status::Checks for $BUCKET
  • GET/PUT/DELETE /requests/:request_number/$BUCKET/:check_id -> Read/Update/Destroy Status::Check inside BsRequest

PROS:

  • Simple, built in, resourceful routing CONS:
  • Longer routes
  • A new prefix to remember (/projects)
  • Can't have a $BUCKET with the same id for the same object (e.g. Package build and commit with id 12345) which we could easily avoid by splitting $BUCKET into two things ($SOURCE_BUCKET and $BINARY_BUCKET) or with a $BUCKET.type or something.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment