IRC log for #rest, 2016-08-07

https://trygvis.io/rest-wiki/

All times shown according to UTC.

Time	Nick	Message
00:18	mamund	use etags and if-match headers to properly handle idempotent updates on shared resources.
00:19	mamund	checkout see "Detecting the Lost Update Problem using Unreserved Checkout: https://www.w3.org/1999/04/Editing/
00:19	mamund	HTTP has this well-defined as of 1.1
00:20	mamund	you can mimic this in HTML FORMS (etag fields) if you wish.
00:20	mamund	you'll need to invent something similar for websockets and other protocols that don't explictly expose idempotency at the network message level.
00:24		ShekharReddy joined #rest
00:35	mamund	as discussed here this past week, if you want to use PATCH, use a PATCH media type. there are ones for both XML and JSON and they include commands for adding, updating, and removing nodes.
01:27		fuzzyhorns joined #rest
01:32	Sna4x81	mamund: You mean JSON merge patch (RFC 7396)?
02:04		_ollie joined #rest
05:16		wsieroci joined #rest
05:32		ralphschindler joined #rest
09:11		wsieroci joined #rest
10:01		graste joined #rest
13:56		wsieroci joined #rest
14:02		tonyacunar joined #rest
14:04		ralphschindler joined #rest
14:06		fuzzyhorns joined #rest
14:14		wsieroci_ joined #rest
14:59		Tomatosoup- joined #rest
15:04	mamund	Sna4x81: yes. that's one of them.
15:04	mamund	there is also one that is a bit more involved: 6902
15:06	mamund	RFC7351 and RFC5261 are XML Patch media types.
15:20		wsieroci_ joined #rest
15:23		graste joined #rest
15:28		wsieroci joined #rest
15:53		foist joined #rest
16:03		fuzzyhorns joined #rest
16:23	Sna4x81	mamund: Ah, yes, I've seen RFC 6902.
16:26	Sna4x81	I like 7396, but changing the Content-Type seems superfluous to me. I know that goes against specs, but it seems like rest has become overly pedantic and forgotten about pragmatics.
16:28	Sna4x81	Looking at some APIs this morning, it looks like Github uses POST for partial profile updates, and they include a _method: "put" property. Google uses PUT for partial updates in their contacts API. I wonder if any of the big guys are using PATCH.
16:31		fuzzyhorns joined #rest
16:50		tonyacunar joined #rest
17:00	Sna4x81	Hey mamund and tonyacunar: I'm leaning towards using POST for updates that aren't complete replacements. I see that frequently (for example, it's what Github does in their APIs), and indeed that's what Roy Fielding seems to suggest.
17:01	Sna4x81	http://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post
17:03	tonyacunar	Thats cool - so then you’ll do POST with a version or you will allow data overwrite as part of posts?
17:07	Sna4x81	tonyacunar: I wasn't going to send a version necessarily. POST /users/ {firstName: 'Jimbob', ...} Creates a user, responds with a location header of /users/x, and with the full user in the body.
17:08	Sna4x81	Then the API consumer can either PUT /users/1 to completely replace that user, or POST /users/1 to do partial updates. E.g. POST /users/1 {firstName: 'Janebob'} just updates the first name.
17:09	Sna4x81	PUT is completely idempotent, and POST may be idempotent but doesn't have to be. The PUT is somewhat superfluous, though, in that POST can also be used for complete replacement by simply including all fields.
17:35	mamund	Sna4x81: REST has nothing to do w/ HTTP
17:35	mamund	and content-negotiation.
17:36	mamund	i write client apps that "sniff" the content type to know how to route/handle the incomming message. if HTTP didn't have a header for it, i'd en up creating my own.
17:36	mamund	POST is absolutely fine for passing changes. HTML does it all the itme. i use it quite often.
17:37	mamund	when the use case calls for fine-grained changes to a large-grained resource, i find PATCH an easy solution and use that, too.
17:37	mamund	for changing just single properties on a large object, I've used Fielding Property Maps.
17:38	mamund	http://amundsen.com/examples/fielding-props/docs
17:38	mamund	lots of HTTP-based otions there. no need to claim one "right" and the others "wrong"
17:38	mamund	and none of them require REST to use them.
17:39	Sna4x81	All right, that's helpful. Thanks. So much reading!
17:40	mamund	LOL!
17:41	mamund	no problem.
17:41	mamund	the easy way to start is just use POST and let the server sort out teh details.
17:41	mamund	if/when that starts to get too complicated/inaccurate, you can move on to using PATCH.
18:05		_ollie joined #rest
18:40		k_j joined #rest
18:40	k_j	should i use camelCase or snake_case in JSON responses ?
19:52	k_j	is there a tool for designing and testing a rest api through js?
20:13		graste joined #rest
20:27		wsieroci_ joined #rest
20:27		wsieroci_ joined #rest
20:28		wsieroci joined #rest
20:31		Tomatosoup- joined #rest
20:36		Tomatosoup- joined #rest
20:40		wsiqueir joined #rest
21:06		wsieroci joined #rest
21:30		_ollie joined #rest
21:36	mamund	k_j : not too much talk about JSON-specific things here
21:36	k_j	mamund, ok, what's the best free tool to design rest api's?
21:36	_ollie	k_j: it's called brain ;)
21:37	mamund	can't name single REST designer, but there are quite a few HTTP-centric ones "API first" style tools to check out
21:37	mamund	apiblueprint, Swagger, RAML are the common three HTTP API description tools
21:37	mamund	there are some server-side (even client-side) code gen for them, too.
21:38	mamund	depends on your prefs, lang, etc.
21:38	mamund	will say that i saw a tool prototype i really liked called Rapido by a friend of mine (Ronnie Mitra) a while back
21:39	mamund	rally design-y for the API (not text-based, mostly drag/drop lines and boxes)
21:39	mamund	but it was just a prototype and i've not seen much insce
21:39	mamund	since
21:39	mamund	frankly, i use pencil/paper for most of my initial designs.
21:39	mamund	other might offer alternatives
21:42	k_j	http://editor.swagger.io/#/
21:43	k_j	i fail to understand completely these editors
21:43	mamund	understanding anything completely is a fail, i suspect
21:44	k_j	on one side you have something written in a language you have to lear, which somehow models both a server and operations, on the other side you have a way to try these operations
21:44	k_j	is that correct?
21:44	mamund	yeah, proly a decent way to put it.
21:44	mamund	that's why i prefer apiblueprint
21:44	mamund	the lang to learn is markdown (w/ some specifics)
21:45	mamund	and buliding the description is actually bulidng a runnable/tesetable instance w/o any genreating step
21:45	mamund	for me, it's a very low-cost way to do prototyping
21:45	mamund	i'm annoyed at the level of typing i need to do, but am happy that it results in a runnig instanace right awawy
21:45	k_j	hmm... but learning a whole new language is time consuming.... it defeats the purpose of a rapid tool for designing an api
21:46	mamund	IMO, it does not defeat the purpose. your view is diff
21:47	mamund	if i can learn something that cuts 50% or more of the effort in design, i'll consider it.
21:47	mamund	i also don't conflate design w/ implementation.
21:47	mamund	i need a design scratchpad or tool to test things out
21:47	k_j	mamund, what do you think about swagger
21:47	mamund	once i know what works, i'll go write th real code
21:48	mamund	swagger is not something i use much
21:48	mamund	tried a few times, but too verbose for me
21:48	mamund	and i don't like code-gen toolking in general so the appeal is not there for me.
21:48	k_j	so you use apiblueprint
21:48	mamund	dods are cute, but i can get the same look/feel from other ways
21:48	mamund	when i want to do prototypes, apiblueprint is what i use
21:49	mamund	right now, i start w/ pencil/paper to sketch things out
21:49	mamund	then use blueprint to make them into a prototype
21:49	mamund	then use the results to work up other docs that will drive the actual implementation
21:51	mamund	but that's just me. that's how i prefer to work.
21:51	k_j	do you also use apiary?
21:52	mamund	yes -- that's the engine that i use to test out my blueprint documents
21:53	mamund	haven't used their other tools
21:54		timg__ joined #rest
22:00		fuzzyhorns joined #rest
22:06		tonyacunar joined #rest
22:10	k_j	i understand the mock server and the production server to send the calls to
22:10	k_j	but what is the debugging proxy
22:10	mamund	hmmm... don't know that.
22:33		sfdebug joined #rest
22:34	sfdebug	does anyone can give me an explanation about "hypermedia as the engine of application state" (HATEOAS)?
22:57	k_j	sfdebug, it's a way to link resources together
22:58	sfdebug	k_j, can you give me an example?
23:00	k_j	sfdebug, <link rel="deposit" href="https://somebank.org/account/12345/deposit" />
23:01	sfdebug	k_j, it must be on REST responses? why? or better, when?
23:02	k_j	sfdebug, it depends on your application, if you need to describe a resource in terms of other resources you would link as above
23:03	sfdebug	what do you mean with "describe a resource in terms of other resources"?
23:05	k_j	a /collections resource is a collection of resources , you can describe the collections in terms of an array of links to each resource in the collection
23:07		tonyacunar joined #rest
23:08	_ollie	sfdebug: HATEOAS is basically the client using links to decide whether a particular action can be executed and then executing it. Assume an order, that's expected to be paid. In that state, the response would contain a link named "payment" to indicate the client can issue the state transition by following it. After the client followed it and the operation succeeded, the order can't be paid anymore. Thus the link would disappear from th
23:09	sfdebug	i got it!
23:09	sfdebug	_ollie, thanks!
23:09	sfdebug	k_j, thanks too!!
23:09	sfdebug	:)
23:09	_ollie	sfdebug: are you using Java as the implementation language?
23:09	sfdebug	no...
23:10	sfdebug	PHP
23:10	_ollie	Okay. I would've had an example implementation handy if so ;)
23:10	sfdebug	_ollie, i think i can understand java's basics...
23:10	_ollie	https://github.com/olivergierke/spring-restbucks
23:11	sfdebug	let me see...
23:12	_ollie	Here's a slide deck with the corresponding info: https://speakerdeck.com/olivergierke/hypermedia-apis-with-spring-7
23:13	k_j	but i am not sure hateos is useful
23:13	k_j	as a concept
23:13	_ollie	It fundamentally reduces the coupling between client and server
23:14	_ollie	I wrote a quick summary of that here: http://olivergierke.de/2016/04/benefits-of-hypermedia
23:15		fuzzyhorns joined #rest
23:15	sfdebug	basically it is the next steps the client "can or must" do after do the first one?
23:16	_ollie	Well, yes. The fundamental point is that it allows you to "encode" decisions for the client to make into a simple "link present or not", whereas otherwise it would've to inspect the payload and replicate the rules for those decisions, which creates the coupling.
23:19		Coldblackice joined #rest
23:20	sfdebug	i can't understand the benefit of this when i think the client already knows the next steps it can or must do...
23:21	_ollie	The client is not really interested in the timing. It's basically coded in a "if link x is present, do that"
23:21	sfdebug	_ollie, so the links that comes in the response MUST be called?
23:22	_ollie	No, not at all.
23:22	k_j	_ollie, but aren't there HTTP verbs for modifying a resource? why should i follow a "cancel" link instead of using DELETE, for example?
23:22	_ollie	What HTTP method you use is specified for the cancel link. In the example implementation you follow the cancel link using DELETE :).
23:23	_ollie	I use "follow" like: issue a request to the link target.
23:26	k_j	ok so the link itself encodes a thing like "it can now be cancelled", it's an helper for the client, which would otherwise apply some complex logic. the client still has to know what to do with the cancel link however. is this correct?
23:26	_ollie	Exactly.
23:27	_ollie	The blog post I linked to above has some details on why the client inspecting the payload too closely creates issues.
23:28	sfdebug	for example, if i have a /albums resource and i do a POST to that an create an album, i must return a link to a /albums/<idalbum>/medias telling that the user can create medias in that album?
23:29	sfdebug	and* create an album
23:30	_ollie	Where that link points is irrelevant. But yeah it'd be a good idea to add that link. The client would've to look out for the special link name then.
23:32	sfdebug	_ollie, but the client doesn't already must or maybe know that it can be done and where to do a POST to create a new media on that created album? that isn't unnecessary send this lot of information?
23:33	_ollie	It doesn't need to know the where as the where is what the link points to.
23:33	k_j	_ollie, one thing i always wondered is if it's in the rest spirit to provide a link without the absolute schema , i.e. http://server/resource . for some reasons which i ll omit, i d like to give relative urls like /resource
23:33	_ollie	You can go full circle and let the client find a form to even dynamically retrieve a form.
23:34	k_j	in all the examples i have seen there always is the full path
23:34	_ollie	However, most clients I see so far, know the payload structure in advance.
23:35	_ollie	I'd recommend to use full links, too. That way, the client can just use the link and dereference it.
23:58		fuzzyhorns joined #rest
23:59	sfdebug	well, i think i understood that, but, if i have some next step that can point to the same resource but that can be listed or created(GET or POST), how can i specify the HTTP verb?

https://trygvis.io/rest-wiki/