add-endpoint

Adding New Endpoints & Features

When to use WebSocket vs HTTP

ShipIt uses HTTP for most operations and reserves WebSocket for a narrow set of cases. When adding a new feature, use this decision framework:

Use HTTP (default) when:

• The operation is a simple read (GET) or mutation (POST/PATCH/DELETE) with a single request-response cycle
• The client needs the result directly (e.g., to update UI state from the response)
• The operation is stateless — any client tab could make the same request
• Examples: fetching file content, renaming a session, creating a PR, saving settings

Use WebSocket only when one of these applies:

1. Streaming output — the server produces incremental data over time (Claude CLI events, deploy progress, terminal output). HTTP would require polling or SSE; WS gives us a natural push channel already connected.
2. Per-connection state — the operation modifies state tied to this specific browser tab, not the user globally. Session activation (activate_session) attaches a runner and file watcher to the connection. Agent selection (set_agent) sets the agent for this tab only. These don't make sense as HTTP because they bind to the socket's lifecycle.
3. Bidirectional real-time interaction — the client and server exchange messages in rapid succession as part of one logical flow: sending a prompt and receiving streamed tokens, answering permission questions mid-turn, interactive terminal I/O.
4. Server-initiated push — the server needs to notify the client without a preceding request: file change events, preview status updates, session status broadcasts, queue notifications.

Gray area — lean HTTP:

• If an operation triggers server-side effects that push WS events (e.g., fork_session triggers a session_list broadcast), that's fine — the trigger is HTTP, the notification is WS. Don't put the trigger on WS just because it has side effects.
• If you're unsure, start with HTTP. It's simpler to test (app.inject()), easier to debug (curl), and doesn't couple the operation to connection lifecycle. You can always add a WS broadcast for notifications on top.