Diagram for REST #364

Closed
wants to merge 1 commit into
from

6 participants

@nevar
Contributor
nevar commented Jan 10, 2013

No description provided.

@seletskiy
Contributor

Excellent work! But I thinks this chart will be more useful if there will be short description about each callback method: what it does, what arguments it consume and what result should be returned.

@essen
Member
essen commented Jan 21, 2013

That's better looking than my diagram. However I was hoping to be able to convert from dia to svg with css styling in the middle, to make it looks better than what dia exports. Do you know how to do that?

@nevar
Contributor
nevar commented Jan 22, 2013

*.dia can converted to *.jpg, *.svg and many other types.
Maybe you can use css after render svg in browser.

Also miss some callback (variances/2).
Need some way to show "default way". Сan more fat arrows?

@nevar
Contributor
nevar commented Jan 28, 2013

Replace .png with .svg

@essen
Member
essen commented Jan 29, 2013

Awesome.

I'll probably include that and try to make css stuff later, bigger fishes to fry etc. I'll merge the few changes mentioned in other PRs before finally merging this, so you'll have a little more work updating it. :) Keep you posted.

@essen
Member
essen commented Jan 29, 2013

I've started merging the changes. Will continue over the next few days.

@nevar
Contributor
nevar commented Jan 30, 2013

I need add #289, #353, #296. I made this In weekend.

@essen
Member
essen commented Jan 30, 2013

Take your time. :)

There'll be a few more tomorrow most likely.

@essen
Member
essen commented Jan 30, 2013

Everything for 0.8 should be in.

@nevar
Contributor
nevar commented Feb 2, 2013

@essen I update diagram. I hope nothing is missed.

@essen
Member
essen commented Feb 2, 2013

Not sure what happens below the if POST, the one that's below if DELETE, if PATCH etc.

@nevar
Contributor
nevar commented Feb 2, 2013

@essen Do you mean that the intersection is not clear where to go?

@essen
Member
essen commented Feb 2, 2013

Yeah. No idea what happens there.

@nevar
Contributor
nevar commented Feb 2, 2013

@essen I removed the intersection. Hope this help.

@nevar
Contributor
nevar commented Feb 9, 2013

All headers are lowercase in diagram

@essen
Member
essen commented Feb 9, 2013

I think I'll just link to the PR in the guide for now. Want to release 0.8 on Monday and there's still REST changes to be done after 0.8 so no rush on getting this actually merged.

@nevar
Contributor
nevar commented Feb 10, 2013

Ok. I will keep it up to date.

@essen
Member
essen commented Feb 11, 2013

Thanks!

@essen
Member
essen commented Feb 12, 2013

I have put a link to this PR in the guide.

@essen
Member
essen commented Apr 11, 2013

Done the POST changes.

@edgurgel
Contributor

How's the state of the REST handler? Is it under heavy development or stable?

@essen
Member
essen commented Apr 13, 2013

It's in the process of being documented. Last API breaking changes should be in now.

@edgurgel
Contributor

Great news. Keep up the good work. 👍

@essen
Member
essen commented Apr 19, 2013

I think we should have one diagram per method type instead of trying to push everything in one.

So we could have a diagram for OPTIONS, a diagram for HEAD/GET, a diagram for POST/PATCH/PUT and a diagram for DELETE.

This should make it clearer what each operation does and what routes it can take. This does mean more work for you though. Think you can handle it? There's one fix I need to do for POST and we should be good API wise.

@nevar
Contributor
nevar commented Apr 20, 2013

What about common element for all diagrams, they will copy to all diagram?

I will wait #424 then start make POST method. In next weekend I will do other methods.

@essen
Member
essen commented Apr 20, 2013

Let's see one like this but I think the beginning part will be cut into its own diagram. I'll push #424 later today.

@essen
Member
essen commented Apr 20, 2013

Pushed 711c21a. Hope that's good.

@essen
Member
essen commented Apr 26, 2013

If you have free time this weekend we can work on it together. Otherwise I'll probably do it directly based on your work.

I think they should be top to bottom (easier to inline in the documentation or in other materials), and there should be these different diagrams:

  • Beginning part, up to resource_exists
  • From resource_exists, for HEAD and GET requests
  • From resource_exists, for POST/PATCH/PUT requests
  • From resource_exists, for DELETE requests

Below each diagram I will put a detailed explanation, so OPTIONS would be explained under the first diagram.

What do you think?

@nevar
Contributor
nevar commented Apr 26, 2013

Okay. I plan to start work on Beginning part + HEAD and GET tomorow. If it not hard also continue and try to make POST/PATCH/PUT.

@nevar
Contributor
nevar commented Apr 27, 2013

I made all diagram. Please review and say what you think.

@essen
Member
essen commented Apr 27, 2013

You went too far for the beginning diagram, should stop right after variances. You have a test for GET there after and you shouldn't, it should only appear on the GET diagram.

@nevar
Contributor
nevar commented Apr 27, 2013

But POST/PUT/PATCH also can path that way. And then have some separate way based on what way they come. Or I miss some thing?

@essen
Member
essen commented Apr 27, 2013

The beginning is a straight line, the rest varies depending on the request and the resource definition. Can't really explain the extra part you put there without looking at the other diagrams.

@nevar
Contributor
nevar commented Apr 27, 2013

Ok. should I remove If-Match and e.t.c. check in begining diagram and repeat it on each method diagram?

@essen
Member
essen commented Apr 27, 2013

Yep, all others should start with resource_exists.

@nevar
Contributor
nevar commented Apr 28, 2013

done.

@nevar
Contributor
nevar commented Apr 29, 2013

Make some correction. Now I think this is final version.

@ZhenguoYang

Cant see the diagram?

@nevar
Contributor
nevar commented Jun 26, 2013

GitHab return all file from raw.* with "Content-Type: text/plain". And you see text.

Save file on disk and open it with your browser and you will able to see diagram.

@ZhenguoYang

Cool, thanks.

@essen
Member
essen commented Jun 29, 2013

Current plans: do the better HTTP part of the guide the coming week, then start the REST part the week after. I'll be looking into adding the diagrams then. However I am looking for a solution that allows easier modifications than with Dia (especially don't want to manually move things around) but that's still pretty, so this is why I haven't merged yet. Thanks for your patience!

@nevar
Contributor
nevar commented Jun 30, 2013

If you know a better tool for diagram, I am happy to remake diagram using it.

Maybe [DOT](http://en.wikipedia.org/wiki/DOT_(graph_description_language\)) will satisfy some requirement.

@essen
Member
essen commented Jul 1, 2013

I looked at dot before but it's not perfect. I'm gonna look harder right now and try things out.

@essen
Member
essen commented Jul 5, 2013

I've started reworking the beginning part of the diagram. I'm experimenting with the SVG format directly which, while not perfect, seems to be very good for making the image look like a structured document with many reusable parts. I will continue doing that and since you have done most of the work I will make them available so you can commit them and get the credit for the commit.

@essen
Member
essen commented Jul 5, 2013

Well this is SVG+CSS but the CSS is inside the SVG so it's still just one file.

@nevar
Contributor
nevar commented Sep 13, 2013

Any news. May be I can help somehow?

@nevar
Contributor
nevar commented Dec 3, 2013

@essen ping?

@jiemar
jiemar commented Jan 8, 2014

how to download the flow diagram

@nevar
Contributor
nevar commented Jan 8, 2014

You can select "View file" in "File changes" and then press "Raw" button. After that choise "File -> Save as ..." in your browser.

Or right click on link and select "Save Link as ...":
REST_beginning_flow.svg
REST_DELETE_flow.svg
REST_POST_PUT_PATCH_flow.svg
REST_GET_HEAD_flow.svg

@essen
Member
essen commented Jun 21, 2014

Hey!

I want to give you a huge thank you for the work you have done here. Even if I didn't end up using it, it proved insanely useful as a temporary resource for people who needed it. Thank you!

I went with plain SVG with Inkscape (same as the small flowchart I did months ago). I'm only adding them now because, well, I finally found the motivation to get through this.

I ended up doing more diagrams than we discussed also.

The diagrams have been added to the repository in both svg and png format. A stub chapter has been added for now, I'm a bit tired to add explanations at the moment. https://github.com/extend/cowboy/blob/master/guide/rest_flowcharts.md

If you find any error, please open a new ticket! Or send a patch (of the SVG only, I'll export the PNG afterwards).

So again, HUGE thanks! Closing this! Thanks!

@essen essen closed this Jun 21, 2014
@edgurgel
Contributor
edgurgel commented Aug 7, 2014

I can't find the rest_flowcharts on the website. Am I doing something wrong?

@edgurgel
Contributor
edgurgel commented Aug 7, 2014

Forgive me! I was looking on the cowboy_rest documentation. I somehow thought it should be there or have a link there. Ignore me

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment