Architecture · Appendix A
API routes
All routes are under /api/v1/. The largest body is 64 KB. A request with no valid auth gets 401, and a missing thing gets 410. A reply that links to files of a project also sets the signed cookies of that project. The routes of the Action need a new OIDC token of GitHub for each request.
| Route | Auth | What it does |
|---|---|---|
GET health | none | Reports that the API runs. |
POST decks | enrollment code | Enrolls a deck with its public key. |
GET, DELETE decks/self | deck signature | Shows the deck, or removes it (Disconnect). |
POST owner/code | deck signature | Makes an owner code (10 minutes). |
POST auth/owner/begin, finish | owner code | Makes an owner passkey. |
POST invites/view | invite code | Shows the project and the owner of an invite. |
POST auth/invite/begin, finish | invite code | Makes a member passkey, and joins. |
POST auth/login/begin, finish | passkey; finish accepts an optional invite code | Signs in, and gives a session token. With an invite code, a member passkey also joins the project of the invite. |
GET me | session | Shows the person of the session. |
GET, POST printers | owner or deck | Lists the printers. A deck registers its printer. |
GET names/<slug> | session | Finds the project of a slug. With ?view=1, it also gives the view of the project, so a project page needs one request. |
GET, POST projects | session or deck | Lists the projects, or makes one (owner). A member gets each project of the session that still has the member. |
projects/<id> and below | session or deck | View, rename, delete; invites, members, public address; prints, live tiles, photos. The rows below are the routes of the notes, the prints, the photos, the queue and the builds. |
PATCH projects/<id>/notes | session | Changes the notes of the project. |
PATCH projects/<id>/prints/<print> | session; owner for title, marks, source | Changes the title, the notes, the marks Test, Ready, Delivered, In use and Rejected (with a note of why), or the source of a print. A member changes the notes only. |
PUT projects/<id>/photos/<photo> | session or deck; a member moves only their own photos | Moves a photo to another print of the project, or to no print. |
PATCH projects/<id>/members/<member> | owner or deck | Sets the GitHub username of a member who joined. |
PUT projects/<id>/repo | owner or deck | Links a GitHub repository, or removes the link with "". |
GET projects/<id>/plans/<plan> | session | Shows a plan with the paths of its models, and its builds. |
GET projects/<id>/plans | session | Lists the plans of pull requests and of tags. |
POST projects/<id>/plans/<plan>/builds | owner or deck | Makes a build with the plates, and starts the slice run with the GitHub App. |
GET projects/<id>/builds/<build> | session | Shows a build with its plates, and the gh command when the stack has no App. |
POST projects/<id>/builds/<build>/plates/<n>/approve, reject | owner or deck | Approves a plate, or rejects it with a reason. |
POST plans | OIDC token of the linked repository, or of a member's fork with an open pull request | Makes a plan, and gives the grant of its models and its PDFs. |
POST plans/<id>/done | OIDC token of the repository of the plan, or of its fork | Checks the models and the PDFs, and marks the plan ready. An older waiting plate with a changed part becomes "replaced". With the GitHub App, the service then writes its comment on the pull request. |
GET builds/<id> | OIDC token of printdeck.yml on main or master | Gives the commit and the plates of the build. |
POST builds/<id>/started | the same | Records the run ID. A failed build goes back to "slicing". |
POST builds/<id>/progress | the same | Records a line of progress of the slice run. The build must be "slicing". |
POST builds/<id>/files | the same | Records the files of the plates, and gives the grant of the build. |
POST builds/<id>/done | the same | Checks the files. The build becomes "ready", and each plate "waiting". |
POST builds/<id>/failed | the same | Marks the build "failed", with the error. |
POST shares | deck signature | Makes a share, with its first grant. |
shares/<id>/grant, end, project, DELETE | signature of the deck of the share | A new grant, the end, the project of the share, or a delete. |
shares/<id>/ready, photo | owner key, or the deck | The Ready flag and note; photos. |
POST projects/<id>/builds/<build>/plates/<n>/send | owner or deck | Sends an approved plate to a printer of its process. |
GET printers/<id>/plates, POST printers/<id>/plates/taken | signature of the deck of the printer | The plates that wait for the printer, with presigned addresses of the bucket; the plate is in the queue. |
POST printers/<id>/queue | signature of the deck of the printer | The files of the queue that are in projects: their places and starts. |
DELETE projects/<id>/queue/<printer>/<item> | owner or deck | Asks the deck to take a file of the project out of its queue. The file must be in the last report of the queue. |
GET printers/<id>/removes, POST printers/<id>/removes/done | signature of the deck of the printer | The files that the owner took out on the project page; the deck took them out. |
POST printers/<id>/live | signature of the deck of the printer | What the printer does now. GET printers has it for the owner. |
/.well-known/apple-app-site-association | none (a file of the bucket) | The webcredentials of the iPhone app, for the passkey sign-in in the app. |
relay/register, relay/push | none for register (a code comes by push); the send token for push | The push relay of the iPhone app, when the stack has the secret of the relay. The app registers here, and the decks post their encrypted messages here. |