Fork me on GitHub
#yada
<
2016-09-01
>
kingoftheknoll01:09:21

I’m curious how a resource in yada and/or strict RESTful approach would conceptually have more than one POST actions for a resource. For example take an imaginary API for cloud resources. All endpoints should take 1-n resource uuids as args.

Option 1: POST takes multiple :fn/:args messages.
POST /instance
- Start
- Stop
- Restart

Option 2: Multiple urls
POST /instance/start
POST /instance/stop
POST /instance/restart

Option 3: More CQRS actions endpoint
POST /action :fn/:args message 
Trouble with Options 1 and 3 is both have variable messages making the request/response dispatch on type and would be ambiguous potentially. You’d probably lose the benefit of swagger there too. Problem with Option 2 feels more verbose and seems to fly in the face of endpoint as resource location with multiple verbs. I’d love to hear the yada perspective on something like this! Cheers!

lmergen06:09:49

Option 3: query params ? POST /foo?method=stop

imre07:09:39

Option 4: PUT /instance/running true

malcolmsparks07:09:33

@kingoftheknoll: In REST, verbs are discouraged. Resources are nouns. POST /instances returns 201 Location /instances/af4b3c. Shutdown that instance with DELETE /instances/af4b3c

malcolmsparks07:09:41

Your suggestion seems a bit like RPC which is creating a bespoke API. One of the REST constraints is a common API

kingoftheknoll13:09:24

@lmergen Option 3 would be a message in the body. @malcolmsparks resources as nouns makes great sense however, using HTTP methods as verbs acting on a resource doesn’t work once you have 15+ actions to can take on it. Thus you’re only given two choices to increase specificity 1) put the action type in body or 2) specify in the url.

lmergen13:09:48

is this really the best approach to have 15 different actions on a single object ?

lmergen13:09:58

that sounds awefully un-REST to me

lmergen13:09:44

the HTTP spec is actually quite strict in how you’re supposed to model these things

grav13:09:50

Hey there! How do I start up a yada-based web service from command line? I can do it from my repl, but not from command line without the service exiting again. I’m using leiningen

grav13:09:54

From the repl, I do

(yada/listener [“/endpoint” (yada/resource {:produces “text/plain” :response (fn [ctx] “hello world”)})])

malcolmsparks13:09:27

@grav: add a @(promise) after you start the server

frozenlock13:09:56

@grav this is due to a recent(ish) update in aleph. You should use wait-for-close https://github.com/ztellman/aleph/issues/265#issuecomment-237705049

frozenlock13:09:42

@malcolmsparks I'm updating an old project and I think I need to replace the old yada.bidi/partial :authorization with a method of yada.authorization/validate. The problem is that I get an error when I try to return {:status 403}. Am I supposed to return something else?

frozenlock15:09:26

Is there a way to make the swagger UI show the endpoints in order of path length, or is that something completely out of yada's reach?

mccraigmccraig16:09:29

i'd prefer them in the same order as my bidi routes @frozenlock

frozenlock16:09:32

Yeah... in my case they are both the same 😛

malcolmsparks17:09:01

@frozenlock are you returning the response, i.e. (:response ctx) - if you just return a map yada will treat it as data

grav17:09:17

@frozenlock thanks for the hint re: .wait-for-close. But it seems to be an 0.4.2-alpha6 feature, according to the github link. Is there a method that works with 0.4.1? Would that be @(promise), as suggested by @malcolmsparks?

kingoftheknoll18:09:07

@lmergen I can’t change the fact that I have many actions. So I made the suggestion that I make multiple ‘resources’ but then that breaks convention with endpoints being nouns. The only way to do this in a true REST manner it seems would be to invent my own methods in addition to GET PUT POST DELETE which of course is silly. I think it comes down to a strict RESTful interface doesn’t work if your interface is any more complicated than CRUD.

grav19:09:20

I am trying to create a WFS endpoint for a Geoserver. The Geoserver sends accept header "accept: *; q=.2” which seems to crash yada. Any hints?

lmergen19:09:46

@kingoftheknoll: in that case I would probably settle with a POST and put a {"action": "create"} in the body or something like that

kingoftheknoll19:09:14

@lmergen I think that’s what I like but with Yada can I make is so swagger knows about multiple message types. Those actions might have different message bodies

lmergen19:09:58

it gets tricky, as soon as you start doing complicated stuff such as optionals and enums/sets the documentation starts to get weird.

lmergen19:09:21

schema validation works fine though, and the code is perfectly sound and reasonable

kingoftheknoll19:09:23

that’s why I keep going back to multiple endpoints. I mean when I comes down to it, the goal is to auto generate these endpoints for customers and documentation. However internally I’m going to have a single endpoint that takes any action message.

kingoftheknoll19:09:49

which comes to another question, can I skip swagger validation on some endpoints

lmergen19:09:44

yes but while that is an idea, you should try sticking to rest as close as possible. so DELETE /instance/:id and not POST /instance/:id/delete. POST /instance/:id/restart is fine though.

kingoftheknoll19:09:28

Another thing that’s tough is the requirements that all actions take a list of :ids to work on. I’m never guaranteed to be working with one resource. So the conceptual metaphor weakens.

kingoftheknoll20:09:50

So the lesser of all evils would be to have POST endpoints for all actions that take a list of ids.

kingoftheknoll20:09:13

That way I can spec all messages with swagger

lmergen20:09:29

you must start considering your set as a representation of resources. it is not the set you are modifying, it is each one of these resources. as such, your set should filter the resources as a parameter.

lmergen20:09:43

and your api design should reflect that

lmergen20:09:00

I think you should work with a base resource like /instances

lmergen20:09:26

which you could GET

lmergen20:09:42

or you could filter the set using query parameters DELETE /instances?ids=5,8,9

kingoftheknoll20:09:03

and then assuming you’d specify PUT /instances/restart?ids=2,3,4 for other actions

kingoftheknoll20:09:03

I could see you killing the max length of a url though pretty quick

lmergen20:09:43

no never a put. puts are supposed to be idempotent. it should be a post.

lmergen20:09:44

btw, I just thought about http's Range field, which would be a great fit for resource collections.

lmergen20:09:31

it's also recommended in several places I see

lmergen20:09:35

anyway I think you just have a problem that your actions don't map to REST in a sensible way. I would suggest mapping these actions as fields of a resource, so POST /instance/:id/restart, or POST /instances/restart, and I think I would use the Range header.

kingoftheknoll20:09:21

@lmergen Thanks for taking the time to chat with me! I'll check that out and I really appreciate the insight!

grav20:09:48

Seems “*” in accept header crashes yada 1.1.31. I’ve created an issue here: https://github.com/juxt/yada/issues/120

grav20:09:29

I guess it’s a special case, so maybe just convert it to “*/*” in string->media-type?

grav20:09:47

Of course it’s not that easy, since it could be “*; q=0.2" or similar. That’s what Geoserver sends me...

lmergen20:09:41

@kingoftheknoll: no problem! it's an annoying problem with many possible solutions, so I would suggest you just choose one that seems right to you. be careful about some of the implied semantics of the http methods such as PUT, though.

kingoftheknoll20:09:44

Totally, thanks so much