DALI-sync requires both GET and POST

[pdowler]

The description of DALI-sync is intended to specify that an endpoint has to treat GET and POST requests equally. This was common practice in earlier protocols that was refactored (pulled out) to DALI.

context: I am thinking about TAP-next and OpenAPI work but this is generally applicable.

As I recall, the use cases are:

1. GET allows for a clickable link (web page, email, etc) that invokes a service
2. POST allows a standard form (web page) to invoke a service (with user input)
   (both without any client code like javascript)
3. client software can be easily written to invoke the service

We also need to evolve to formulate more complex requests (service invocations)...

However, this requirement kind of forces us into certain implementation details (url-encoding, application/x-www-form-urlencoded, etc - see #40 for more gory details) that start to cause pain when we want to declare APIs using something like OpenAPI and loosely couple the payload on the wire (e.g. to chose something with more structure like json).

At a minimum, this requires a fair bit of duplication in an OpenAPI spec, but I think that the idea of separating the wire protocol (payload delivered) means the above basic use cases 1 and 2 become large obstacles to moving forward and I feel it is only partly the generic browser client (no javascript) but also trying to have both GET and POST.

---

aside: In the VOSpace spec these request APIs are generally "POST a document to endpoint" and it isn't that hard. We (misguidedly) added some "GET with params" for what we thought were simple use cases we could optimise, but then when we write clients we completely ignored them in favour of the core API behaviour.

[msdemlei]

On Mon, Apr 28, 2025 at 01:30:41PM -0700, Patrick Dowler wrote: 1. GET allows for a clickable link (web page, email, etc) that invokes a service

For the record, I always liked this and have used it many times. Can we figure out why OpenAPI is so uptight about treating two methods equivalently (except for cacheability, which for our queries rarely is a problem)? Perhaps there isn't a strong reason and it can be fixed at their end?

[pdowler]

I agree that those really basic use cases and equivalence of GET and POST are convenient when I want to do something manual. It isn't that OpenAPI cannot deal with it as shown in the TAP-sync.yaml file here: ivoa-std/TAP#8

I did have to declare each param in both methods (plus in TAP-async), so this is probably close to maximum amount of duplication one might see in an IVOA API.

The differences between GET and POST are more or less the normal diffs for http: url-encode parameter values in the GET query string, form or multi-part encoding as mentioned in #40 ... but easily equivalent.

The extra pain will come if/when defining an API with some other kind of payload, eg a json document. That is fine as "POST json doc" but there is no non-horrible way to define an equivalent GET (URL-encode json in the query string? ugh) that usefully satisfies that first GET use case.

---

I don't think OpenAPI is uptight about this per se, aside from the fact that you have to duplicate declarations (and make sure they are consistent)... I expect it reflects a design philosophy that there should be one way to do something and so declaring two ways is inconvenient.

I don't think we need to solve this immediately, but we will have to reconsider the pros and cons of those two use cases and whether DALI-sync can/should continue to require both GET and POST.

[Zarquan]

Even just thinking about this is painful.

The extra pain will come if/when defining an API with some other kind of payload, eg a json document. That is fine as "POST json doc" but there is no non-horrible way to define an equivalent GET (URL-encode json in the query string? ugh) that usefully satisfies that first GET use case.