Removing parameters for XRPC procedures

[silverlyra]

The Lexicon spec currently allows both query and procedure endpoints to specify a parameters type. This means that a procedure (HTTP POST) could specify two input types: one for the URI query string (parameters) and one for the request body (input).

In practice, this doesn’t seem to be in use anywhere in the Bluesky-published lexicons – there are 66 query entries with parameters, 46 procedures with an input, but 0 procedures with parameters.

Is there a rationale for permitting both parameters and input on procedure endpoints? I’m working on an AT protocol / Bluesky client in Rust, and I could simplify code generation and make it more idiomatic if I could assume that a procedure will only specify an input, and never parameters. (The atrium project already makes this assumption.)

[bnewbold]

One common use for query parameters on an HTTP POST is with binary payloads, aka file upload. We (Bluesky) currently use this functionality in at least one unspecified/internal Lexicon endpoint.

Alternatives for upload metadata are adding additional HTTP headers; using multipart/form uploads; and putting upload bodies in JSON using base64 encoding (or similar). None of those feel like great options.

As an aside, a related question is whether atproto would ever support the proposed HTTP QUERY verb, which is like GET but includes a body. Actually, whether GET can include a body is sort of ambiguous. Almost no libraries support it, but last I remember the RFCs leave the door open, and software like Elasticsearch does take advantage of this for larger query bodies. HTTP query parameters have ambiguous size limits, and being able to do fancy queries (pure "read", no state mutation) is a good use case for HTTP QUERY. I don't think we currently have any plans to support HTTP QUERY in atproto though, just noting that the "body or query parameters" question isn't always one-or-the-other in library API design.

[silverlyra]

ahh ok – thank you for clarifying this 🙏🏻

binary payloads, aka file upload

I see, so by combining parameters and input, the uploadBlob route could actually specify (e.g.) where the blob is destined for, as opposed to the behavior today where the API can’t decide if a blob is acceptable until the client tries to reference it somewhere.

Alternatives for upload metadata are adding additional HTTP headers; using multipart/form uploads; and putting upload bodies in JSON using base64 encoding (or similar). None of those feel like great options.

Yeah, there are real downsides to be found in all those options. Using parameters will work – as long as there’s no need to pass structured (JSON) data alongside the binary, at which point you’d only have other not-great options (e.g., %-encoded JSON in the query string).

multipart/form-data is how I’ve solved this in the past (on an internal API project at a previous job – any route which had Blob input(s) would transparently add a multipart wrapper), and personally I think it’s the least bad of those three options, with widespread support in HTTP clients and servers.

(I can think of another ATp-specific 🦇 cursed alternative — the protocol already uses CBOR for subscriptions, which could pack the binary data inline with little overhead. 😛 Although trying to build such a payload without first reading the whole file into memory is probably something most CBOR serializers would have no way of doing.)

whether GET can include a body is sort of ambiguous

It’s discouraged in RFC 9110. A standard (and widely-supported) QUERY verb would be great, but idk if there’s any momentum on the I-D.

I think, for my code generator case, I’m going to assume that no procedure will have a JSON input and parameters. When/if endpoints appear have parameters and take */* for input, I’ll just add a blob or file field to the generated parameters type. 😎

[bnewbold]

I guess they had a side-meeting at the IETF a couple weeks back: https://datatracker.ietf.org/doc/minutes-119-httpbis/#query-method

I think that set of assumptions around procedure and query params is likely to hold, and could result in a cleaner library API, but we will reserve the right in the spec to combine query params and JSON-bodied procedure. Seems like the sort of thing that we can leave for "final-final" decision on at... the IETF!