Skip to content

docs: Reshape Endpoints & APIs concepts, archive deprecated streaming#673

Merged
developerjamiu merged 2 commits into
mainfrom
concepts-phase2-pr2-endpoints-apis
Jul 6, 2026
Merged

docs: Reshape Endpoints & APIs concepts, archive deprecated streaming#673
developerjamiu merged 2 commits into
mainfrom
concepts-phase2-pr2-endpoints-apis

Conversation

@developerjamiu

Copy link
Copy Markdown
Contributor

Phase 2 IA, PR 2 of 7 (tracked in #671): reshapes the Endpoints & APIs pages and moves the deprecated streaming API to the archive.

What changed

  • Error handling & exceptions: added a "Handling errors on the client" section (the ServerpodClientException hierarchy and the -1 connection-error case) and a "Don't leak sensitive data" section. Corrected the client exception name from ServerpodException to ServerpodClientException.
  • Streaming: added a worked example (live updates for a filtered query, using a streaming method plus a per-room server-events channel). Moved the deprecated "Streaming Endpoints" section to the archive, fully preserved with a banner.
  • Working with endpoints: added "Point the client at each environment" (choosing the client URL per build with --dart-define).
  • Endpoint middleware: renamed from "Middleware" to disambiguate from web-server middleware, with a cross-link. They are different APIs (pod.server.addMiddleware versus pod.webServer.addMiddleware).
  • Configure HTTP calls: completed the conditional-import stub sample.
  • Endpoint inheritance and File uploads: conformance, plus a fix (config/password.yaml to config/passwords.yaml).

Verification

Checked against the framework source: the client exception hierarchy (serverpod_client_exception.dart), createStream and postMessage (session.dart), and the two distinct middleware APIs. The --dart-define client-URL pattern is standard Flutter, and the conditional-import stub mirrors the page's existing platform-native example.

Notes

Closes #648.

@developerjamiu developerjamiu self-assigned this Jul 6, 2026
@developerjamiu developerjamiu added documentation Improvements or additions to documentation enhancement New feature or request labels Jul 6, 2026
@developerjamiu developerjamiu requested a review from Zfinix July 6, 2026 11:58

@Zfinix Zfinix left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved, non-blocking

Comment thread docs/06-concepts/01-working-with-endpoints/01-working-with-endpoints.md Outdated
Comment thread docs/06-concepts/01-working-with-endpoints/02-endpoint-inheritance.md Outdated
Comment thread docs/06-concepts/01-working-with-endpoints/04-middleware.md Outdated
Comment thread docs/06-concepts/04-exceptions.md Outdated
Comment thread docs/06-concepts/15-streams.md Outdated
Comment thread docs/06-concepts/15-streams.md Outdated
Comment thread docs/06-concepts/15-streams.md Outdated
@developerjamiu developerjamiu enabled auto-merge (squash) July 6, 2026 15:49
@developerjamiu developerjamiu merged commit 5ca9687 into main Jul 6, 2026
4 checks passed
@developerjamiu developerjamiu deleted the concepts-phase2-pr2-endpoints-apis branch July 6, 2026 15:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add Client-side error handling + practical streaming examples to framework docs

2 participants