Clojurians Log v2

This should work: ((resource “hello-world”) {:request-method :get})

Parametrized resources accept the parameters as function arguments and return an actual handler function.

@ejelome ^^ got you an answer. see above.

@ejelome 2 things. 1) I think testing defresource directly isn’t valuable. My opinion. defresource is already tested within liberator’s source code. 2) If you still feel like you need to test it, just check out liberator’s test suite on how to do it. https://github.com/clojure-liberator/liberator/blob/master/test/test_defresource.clj

probably an e2e test would be better in these cases

I had the impression that the OP simply wanted to test his resource and struggled with how parameters would be passed. That's a valid and proper test. OP might have simplified for the sake of example I guess.

Regarding the detailed messages: the server returns an error if the username was already taken. But this could be the case when a user tried to register the first time or when he/she wants to change the username.

For the server it’s the same operation, e.g. PUT /users/ordnungswidrig/name but you want to show different error messages to the user.

I had good experience with a server returning a keyword for the error, e.g. :username-conflict and the client uses a dictionary to lookup an appropriate error message depending on the interaction.

That's kind of what I am trying to do.

Actually exactly

But I want to check all errors that leave Liberator to adhere to a schema. And as a bonus, I would like to make it easy to find the source of :username-conflict, i.e. where in the code it was emitted.

there’s grep for that 🙂

(I'm also passing all non-error data through functions in :handle-ok, to make sure they also conform to the spec.)

Hm, I guess I could pass :error/username-conflict and just check whether the namespace is error, to guarantee that the grepping will not become too difficult...

yes, namespaced keywords is the way to go

How are people with really large code bases and different teams working on API and UI doing this? I.e. they have to pass around some kind of documentation...

well, my personal take on this is to stick with the ideas behind REST. One important constraint is that the only documentation is the description of the media types of the resources. This includes the semantics, error cases etc.

On another topic: @ordnungswidrig Do you have an answer to https://github.com/clojure-liberator/liberator/issues/237#issuecomment-287816541 ? I.e. how to do API documentation with Liberator without Swagger?

That must be sufficient for a well formed user facing client to reason about the system.

I actually commented on that ticket: https://github.com/clojure-liberator/liberator/issues/237#issuecomment-287810782

Oh you meant that example? No I did not came up with one.

This very much depends on the actual usecase, but people nowadays use HAL, Collection+JSON etc. as the underlying media types and there is documentation tooling support for these.

My knowledge of the terms you used was also too small to fully grasp what you propose as an alternative.

😉

So in recent projects we used application/edn and clojure.spec specification for the interop. The resources linked to each other and the links used a well defined set of relations, e.g. “child”, “parent”, “authorization”

media type, hypermedia, resource deployment (you refer to (defresource)?), the relation delete, again media types, ...

HAL http://stateless.co/hal_specification.html might be a good start on the ideas of hypermedia.

The wikipedia definition of hypermedia, e.g., was rather confusing in this context: https://en.wikipedia.org/wiki/Hypermedia

yes, it’s data pointing to other data 🙂

Important is that if you have a, say a resource of type “order” that links to a resource “xyz” and the link is qualified as the relation “payment” that you have documented what this relation means for a resource of type “order”.

Thanks for the link.

And what is the expected semantics when you POST or DELETE to that link. (e.g. “initiate paymen” and “cancel payment” or “refund payment”)

That’s only documented for the resource types, not for a particular URI. This is a main difference to the RPC based API descriptors like swagger.

Thanks a lot for all that input. I'll read and then chart a new course taking into account all that new data 🙂

One step after the other 🙂

omg, clojure is soooo awesome:

clj
(defn error-namespace? [s]
  (= (namespace s) "error"))
...
(s/constrained s/Keyword error-namespace?)

I start with an extremely elaborate and thought through way of managing error codes, that only involves a registry and some macros and namespaces and ... And I end up with (basically) a one-liner.