LearnReferenceBlog
Protocol

Shared behavior

Common properties of the various endpoints.

The HTTP API is only available over HTTPS. Servers should actively refuse non-secure connections, or must at the very least redirect to the corresponding secure endpoint.

Client libraries can assume all requests will always be over HTTPS.

The protocol currently supports TLS 1.2 and TLS 1.3.

Due to the generic nature of the protocol, client apps may often need to perform multiple queries to populate a single view. This, combined with a heavy use of SSE­, meant that the browser connection limit of HTTP/2 was too limiting. As a result HTTP/2­ (or 3) support is required to serve the HTTP API.

The HTTP API is designed to be available to web applications hosted on domains that differ from the API domain. As a result CORS­ is a requirement and is enabled for all origins on all endpoints.

Access-Control-Allow-Headers: Authorization,Content-Type,X-Baq-Client-Id,Last-Event-Id,X-Baq-PublicKey
Access-Control-Allow-Methods: HEAD,GET,POST,PUT,DELETE,OPTIONS
Access-Control-Allow-Origin: *
Access-Control-Max-Age: 43200

The following headers can be used on all endpoints.

X-Baq-Client-Id

Random, transient, 128-bit identifier of the current client.

  • Hex-encoded, all-lowercase, without any spaces.

  • Used to filter out events sent through the SSE events­ endpoint when they result from actions performed by the same client.

  • Strongly recommended on all calls for apps that use server events.

X-Baq-Content-SHA256

SHA256 hash of the request content, hex-encoded.

  • Makes it possible to sign the request content.

  • Optional in protocol version 1.0.

The HTTP API is designed to always provide up-to-date data. Therefore all endpoints, with the exception of GET record_blob­, will always return the following:

Cache-Control: no-cache

Content negotiation with the help of the Accept header is unavailable and ignored throughout the entire HTTP API.

For all endpoints except POST new_blob­ and GET record_blob­, the only expected content format is the following:

Content-Type: application/json

All endpoints return errors that follow RFC 9457­. They return a standardized JSON object that makes it easier to handle errors programmatically.

Properties

  • type URI

    • Unique identifier for this type of error.

    • Must be among the documented protocol error types.

    • Also a valid HTTP URL to learn more about the error.

  • status int

    • HTTP status code of the response.

  • title string

    • Human-readable title of the error.

Error types

Coming in protocol version 1.1.

The HTTP API accepts the OPTIONS verb on all endpoints to support CORS. This includes the user’s entity domain itself.

OPTIONS /api/alice/records/alice.baq.run/7b1540ef89214c0da205144ab9a457fb HTTP/2
Host: baq.run
Access-Control-Request-Headers: x-baq-client-id
Access-Control-Request-Method: GET

The server then returns the appropriate Access-Control headers.

HTTP/2 204 No Content
Access-Control-Allow-Headers: Authorization,Content-Type,X-Baq-Client-Id,Last-Event-Id,X-Baq-PublicKey
Access-Control-Allow-Methods: HEAD,GET,POST,PUT,DELETE,OPTIONS
Access-Control-Allow-Origin: *
Access-Control-Max-Age: 43200

Trying to create a new record with an empty object will fail.

POST /api/alice/records HTTP/2
Host: baq.run
Content-Type: application/json

{}

The server returns a unique error type for this problem, and a general explanation of what happened.

HTTP/2 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://baq.dev/error-types/new-record/400-missing-properties",
  "status": 400,
  "title": "The record creation request is missing some required properties."
}
© 2024 Quentez