Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Diagram for REST #364

Closed
wants to merge 1 commit into from

6 participants

@nevar

No description provided.

@seletskiy

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
Owner

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

*.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

Replace .png with .svg

@essen
Owner

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
Owner

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

@nevar

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

@essen
Owner

Take your time. :)

There'll be a few more tomorrow most likely.

@essen
Owner

Everything for 0.8 should be in.

@nevar

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

@essen
Owner

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

@nevar

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

@essen
Owner

Yeah. No idea what happens there.

@nevar

@essen I removed the intersection. Hope this help.

@nevar

All headers are lowercase in diagram

@essen
Owner

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

Ok. I will keep it up to date.

@essen
Owner

Thanks!

@essen
Owner

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

@essen
Owner

Done the POST changes.

@edgurgel

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

@essen
Owner

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

@edgurgel

Great news. Keep up the good work. :+1:

@essen
Owner

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

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
Owner

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
Owner

Pushed 711c21a. Hope that's good.

@essen
Owner

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

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

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

@essen
Owner

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

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
Owner

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

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

@essen
Owner

Yep, all others should start with resource_exists.

@nevar

done.

@nevar

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

@ZhenguoYang

Cant see the diagram?

@nevar

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
Owner

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

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
Owner

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

@essen
Owner

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
Owner

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

@nevar

Any news. May be I can help somehow?

@nevar

@essen ping?

@jiemar

how to download the flow diagram

@nevar

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
Owner

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
@edgurgel

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

@edgurgel

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
Commits on Apr 29, 2013
  1. @nevar

    Add diagram for rest

    nevar authored
Something went wrong with that request. Please try again.