How does one actually return one or the other for a given request?

According to the “Responses” chapter in the manual, it looks like the answer is to manually construct the switch in the response function.

is there any specific reason you want to return one over the other?

usually if you offer multiple representations it's for the client's convenience

so it would be the client asking for one or the other and then what gets returned would be decided by yada during content negotiation

@jonathanj: Here's how it works:

1. You declare the representations your resource can support 2. yada does the negotiation (proactively, reactive is on its way, not ready yet) 3. yada calls your response function with the results of the negotiation process contained in the ctx argument 4. You decide what to do - you can manually switch or you might return some data, in which case yada will try to automatically coerce if for you

So yes, it is manual, unless you rely on yada's automatic response coercion capabilities - and its protocol based so you can add your own

There are unfortunate knock-on effects to all that though, like if your two representations are JSON and XML, there’s no obvious intermediate data structure that can be encoded into a reasonable representation of both, so you end up having to write this switch in your 200, 404, 500, etc. handlers.

But it’s all kind of stuffed into one resource.

Yes, but you can programatically create such constructions

Do you need to return the representation in 404 and 500?

Typically they would return something different. It isn't idiomatic to return the same JSON/XML data for them as you would for a 200

I’m not too sure I understand, wouldn’t the content of the response be wildly different for 500 and 200?

Namely “Here’s the failure” and “Here’s the successful result”?

I guess if you’re constrained to describing your result as a schema then probably you can’t actually use something like XML attributes?

I think that perhaps it might be best to simply have separate resource hierarchies, keeping resources simpler seems like the more manageable solution.

Yes, the content of a 200 response would be wildly different from a 500 one. So then I don't understand the question.

I think I'm beginning to understand it though 🙂

I was just pointing out that you’d likely have to repeat the same kind of logic (albeit slightly different) for each response handler

If there is an error, yada renegotiates the representation. So your 500 response can declare it only response with text/plain, while your 200 responds with XML and JSON

there's no obligation for your error responses to support the same media-types, etc. as your 200 response

That’s true but it’s a bit rude, for example I don’t think SOAP actually allows that.

Why is it rude?

The client is saying 'I'm happy with JSON, XML and text/plain', so it gets what it's asking for

If you client is saying 'I'm only happy with JSON', then yes, you have to support a JSON-formatted error

If the client says it’s happy with JSON and XML but not plain text then your 500 response that is only available in plaintext is invalid or what?

but mostly these will be similar for every resource in that case and you can weave them in to all your resources - this is the reason resources are described in data

Yes, if your error code can only produce plaintext, then you'd get a 406 situation in that case

I guess this would actually be specified in your API, so a request of that fashion would be a fault of the client’s.

The question is, would you produce a 406 or a 500?

I'm not aware of any substantial advice in the RFCs for this situation

I think a 500 without a message body would be the right thing to do, you shouldn't reasonably be able to recover from a 500

I think if you're writing a public API for general consumption you should try to support a reasonable number of media-types and should expect that clients know how to cope with plaintext as a fallback.

If it's an error and they insist on JSON only, just don't return anything besides the error code.

@malcolmsparks: That seems like good advice, thanks.

RFC 7231, Section 5.3.2 says that servers can reply with 406 (Not Acceptable) or disregard the Accept header and send whatever it wants. We typically use the application/vnd.error+json media type for error messages, so we send that in the message body.

I can’t seem to find the part in the manual that explains how to capture path parameters.

I’m trying to match a path like /notices/:domain, so I have a route like

[“/notices/“ [[“” global-notices] [“:domain” domain-notices]]]

If I visit /notices/ then I see my global-notices resource, if I visit /notices/arst then I get an exception:

java.lang.IllegalArgumentException: cannot treat nil as HTTP response for request to '’

And I have no idea what this exception is trying to tell me.

If I change the route from ”:domain” to ”domain”, then I can visit /notices/domain (literally) and see the resource I was expecting, but obviously no path parameter is being captured.

Oh, it needs to be [[:domain] domain-notices].

Yes. It's bidi. A lone keyword means something different: a method match

Which is one thing I dislike about Compojure (matching methods) I wish the bidi author hadn't copied that

@jonathanj: this isn't going to excuse the bad error message but it's one that aleph emits when you return nil as a response, which is what is returned from the bidi matching process. I can't think of a reasonable way to avoid that error other than telling everyone to back stop their route structures with a catch all: [true (yada/handler nil)]