XPRC

XPRC is the standardized HTTP API convention used throughout the AT Protocol for client-server and server-server communication. It provides a consistent way for applications to interact with Personal Data Server (PDSes), relays, AppViews, and other services in the ATmosphere.

XPRC enables a wide range of interactions within the AT Protocol, such as fetching and creating content, managing user accounts and profiles, synchronizing data repositories between services, uploading blobs, and facilitating user interactions.

Basic Structure

XPRC requests follow a simple pattern:

• All API endpoints begin with /xprc/ followed by a Namespaced Identifier (NSID)
• The NSID identifies the specific lexicon schema that defines the request and response formats
• Requests are either queries (HTTP GET) or procedures (HTTP POST)

For example, a request to fetch a user's profile might look like:

GET /xrpc/app.bsky.actor.getProfile?actor=alice.bsky.social

Key Features

Request Types

XPRC supports two primary request types:

• Queries (HTTP GET): Used for retrieving data without changing server state
• Procedures (HTTP POST): Used for operations that modify data or state

The distinction follows standard HTTP REST semantics, with queries being cacheable and procedures being non-cacheable.

Parameters and Data (WIP)

• URL Parameters: Simple data types passed in the URL query string
• Blobs: Binary data like images handled through specialized upload/download endpoints

Authentication

XPRC uses several authentication methods:

• OAuth: The primary authentication method for client applications
• JWTs: Used for session management and service-to-service communication
• App Passwords: Special credentials that provide limited access for third-party applications

Pagination

For endpoints that return large sets of data, XPRC uses cursor-based pagination. Initial requests are made without cursor parameters. If more data is available, the response will include a cursor value that must be included in follow-up requests to retrieve the next batch of data. This continues until no cursor is returned, indicating the end of the dataset.