https://github.com/for-GET/http-decision-diagram/blob/master/doc/README_system.md

I'm working with @seancribbs to add PATCH support to webmachine, and he suggested I look at this project for a guide. If someone could answer a question for me, I'd greatly appreciate it.

Is PATCH fully supported by the current design? I can see Accept-Patch headers specified, which suggests it is at least partially supported, but reading the HTTP spec for PATCH tells me that I should be able to get a 409 response when using PATCH, and I cannot see in the current flow how that could happen - I'm assuming that we would follow true at is_method_create and is_method_process, however there is no flow after that that can take us to a 409 like there is for PUT.

Where is says is_process_done -> 202 Accepted

I think it should split, if the operation could be complemented within the request lifetime it should lead to a 201 Created, if it accepted for future processing, then yes, 202 Accepted.

We actually had this happen at some point with a Webmachine server:

1. Client sent 'Accept: application/json' with a 'GET /foo'.
2. /foo doesn't exist, but the standard 404 error message wants to have a 'text/html' body.
3. Client gets sent a 406 (Not Acceptable) instead of the 404 that would be more accurate/useful and less surprising.

Proposed solution: have a hook for error message generation to generate an acceptable media type for them, or to omit a body on the error if such an acceptable media type doesn't exist.

Nice diagram.
The flow does not specify checks for required preconditions (If-Match required) and the 428 response if omitted.

Some HTTP statuses may leak out information, so it's better to alter them.

While one can do so in override, maybe there should be a more specific way to override statuses just from the perspective of leaking out information.

Thanks to @mootboy @kvakvs @sstrigler - a possible enhancement popped up today - the retrieve:missing callback checks if the resource is missing, but not if the representation is missing, which is what 404 is supposed to check against.

alternatives:

• leave it as today = leave the content type handler to decide whether to force a 404
• introduce a missing_representation callback; where? not sure

Hi,

while adding support for conditional requests to spray I discovered a problem in the diagram. The docs state that he diagram follows the indications in httpbis although Conditional Requests - Section 6 suggests that:

• C10 if-match-matches: true should point to E11 and
• E12 if-none-match-matches: false should point to J10

Do you intentionally deviate from httpbis here and try to adhere to RFC2616?

query params should be defined somehow via a callback, in order to produce uri templates (when adding link support), or when responding to OPTIONS

http://for-get.github.io/http-decision-diagram/httpdd.fsm.html

• keep/switch from jointjs
• elements should be read-only
• view should be scalable
• view should be closer (visually) to the PNG version
• elements should have a popover
• ...
• go wild, and disobey all the above!

PS: have a look at https://github.com/for-GET/http-decision-diagram/blob/master/httpdd.fsm.html.coffee to see some of the obscure workaround/assumptions when processing the JSON file

Currently the diagram is unaware of this header, for none of the flows/methods, although this is a very good way of minimizing round-trips.

Ref: http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-22#section-3.1.4.2

What is a partial put?

Like #3 states, content_types_provided:handler is only called for GET/HEAD/PUT but not for POST.

Similarly, as https://github.com/basho/webmachine/issues/122 states, content_types_accepted:handler is only called for POST when post_is_create is true, and for PUT when is_conflict is false, but not for regular POST

Proposed resolution
content_types_accepted:handler should be called uniformly, regardless of the invoked HTTP method, right about where known_content_type is called. If it's known, then handle it (ie. translate it to Context)
content_types_provided:handler should be called uniformly, regardless of the flow (method, status code) IF there is a Content-Type response header set, and has_resp_body is false, right after webmachine_decision_core:respond handles the logic for HTTP status codes & headers.

Am I right in understanding that 404 should be dealt with before entering the system block? So in effect, there's a decision to be made before entering the decision state machine, of whether or not to enter it in the first place?

Why would content_types_provided be method-dependent?
Why is it not called on POST (when post_is_create is false) ?

I don't see it in the docs. The closest I've found is: https://github.com/for-GET/http-decision-diagram/blob/master/doc/README_request.md#from_content--in

this decision diagram may be at least HTTP-version independent, if not protocol independent

Food for thought:

• leave the catch-all for non RFC2616 methods
• add conflict/409 check for PATCH just like for PUT
• extract the create/process block into a "standalone" FSM

Ref: #35 (comment)

I can only think of using this callback for checking against known deserializers, eg. is this application/json or application/...+json, then check if this is valid JSON.

But

• why check for valid syntax, if this is maybe not a known_media_type (b5 - 415 Unsupported Media Type?
• http://stackoverflow.com/a/12891726/465684 400 is supposed to incorporate 422 Unprocessable Entity, thus one has to also check if the message makes sense (ie. validate against JSON Schema, validate logical rules)

Proposed resolution
Check for known_media_type before malformed_request

This diagram is amazing!

Any chance of arranging it slightly for a more printer-friendly version? It belongs in a frame!

This is a question about understanding the path (i.e. the logical flow) to generate a 400 Bad Request when creating a resource via POST. (Note: I've referred to the Omnigraffle document in writing this; if it is not up-to-date, I would be missing some new information.)

First, I want to mention some relevant creation (i.e. the "create" section) behaviors from the decision diagram:

• If create_partial_put is false then respond with 400 Bad Request. (This seems reasonable to me.)
• If create_has_conflict is true then respond with 409 Conflict. (This seems reasonable to me.)
• If create_path is false then respond with 500 Internal Server Error. (But I don't the meaning of create_path; see #43)
• If create is false, then respond with 500 Internal Server Error. (This seems reasonable; however, what about client errors? More on this next.)

It seems pretty clear that resource creation must happen in create. But as I show above, if a POST resource creation fails, the decision diagram does not provide an opportunity for a 400 Bad Request response.

Next, I want to figure out where client validation should take place in order to generate a 400. If what I've written above is accurate, then resource validation must happen before the "create" block. So, looking around, there are only two prior checks that can result in 400 Bad Request: from_content and is_request_block_ok.

• I see that from_content will not run if has_content is false, therefore it would be possible for a malformed client POST to bypass it. Therefore, this does not seem like a smart place to put validation logic for a POST body.
• By the process of elimination, is_request_block_ok would be the place to validate a POST payload.

Is my logic accurate? Did I miss anything?

Now, an opinion: if I'm right, it seems unfortunate that is_request_block_ok is the correct place to do POST payload validation since it happens so much later in the decision diagram. I would expect POST-related logic to be 'closer' together.

For the point of argument, why not make a POST request's payload processing happen during the 'create' block? That would offer the advantage of letting the 'accept' block run beforehand -- why do the creation if the acceptance criteria are not met?

CORS is rather common
process_options : in should call specific callbacks for setting access-control-* headers

in the light of http://tools.ietf.org/html/draft-ietf-httpbis-http2-03

I don't understand the context or purpose of it. Thanks in advance for helping me understand.

P.S. I presume that create is where the actual resource creation would/should happen. Since create_path happens immediately before, I though that would be enough of a clue to figure it out, but I'm still unsure.

#23 implies creating a block similar to the error block where one would do conneg on a specific set of provided MTs, just that instead of errors, we now want to communicate choices

The questions listed in the v4 readme would be easier to follow if the decision point references (f4, i14, n14 etc.) from the v4 draft were included for each question - these questions then serve as a slightly more detailed explanation of those points than is given on the flow chart image.

Similarly to #1 , how can one check if the request forbidden before even checking if this is a known_media_type?

Proposed resolution
Check for known_media_type before forbidden

I cannot find anything pointing to this check in the RFC, and if I think about it.. there are other reasons why a 501 Not Implemented can be triggered e.g. Expect request header

I'm thinking of removing this check in favour of the "bucket" is_request_ok which can catch anything.

@adean any input?

see #50 (comment)

process_options: in can (should?) output more than just Accept-Patch

e.g. Accept-Post, Accept-Put
e.g. http://tools.ietf.org/html/draft-nottingham-json-home-03

multiple things to consider

• terminating a successful flow in create/process, rather than response
• not handling Content-Location (see #17)

Webmachine decision core and the resource callbacks (can) set headers almost anywhere, which easily leads to headers being set for HTTP status codes where they don't make sense, eg. https://github.com/basho/webmachine/issues/114

Proposed resolution
Mark possible headers as meta-data, and only set a subset of those as response headers at the end of the request processing flow ie. webmachine_decision_core:respond and finish_request resource callback. This would make respond and finish_request encapsulate logic around the HTTP status codes..

http://tools.ietf.org/html/draft-ietf-httpbis-p5-range
https://tools.ietf.org/html/draft-ietf-httpbis-p4-conditional-26#section-6

As stated in #8 (comment) the v3 decision diagram was created to reflect RFC 2616.

It should be visible what is, and what is not part of RFC 2616, httpbis, any other RFC.

visible may not mean "on the diagram" (in order not to overload it), but options should be investigated into at least marking the non-RFC-extensions on the diagram image file

What is the idea behind the decision branch i7 moved? As best as I can tell, it serves only as a possible short-circuit for skipping the next decisions moved_permanently, moved_temporarily, gone_permanently.

given 307 & 308, is there a good reason beyond “legacy” compatibility to support 301 & 302?

the diagram went KISS and chose 307 & 308 in 49cc4b7

In the current form, the diagram does not allow sending a payload when using TRACE or OPTIONS

Is it being used on a considerably large scale?

The issue is that removing it might simplify the flow, and the effort for #18

Ref: http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-22#section-6.4.1

transaction also needs to handle links, at a basic level for #23 to be fully completed

is_*_ok callbacks should probably be renamed to is_*_block_ok for better clarity

Ref: #8

the resource should probably be self-aware of the path it is instantiated on, otherwise it's impossible for it to produce a response with a rel=self link

it could also just call the dispatcher, which would search in the dispatch config for a resource match, but if the resource is served from multiple locations, then which is the canonical location?

temp idea: canonical_uri callback

the link has an incorrect link to the old repository of this code (http-headers-status)

What should missing_has_precondition be checking? There's no documentation for it yet, and no implementation in for-GET/machine.

http://tools.ietf.org/html/rfc6585#section-5 after B22

http://tools.ietf.org/html/rfc2483

Like https://github.com/basho/webmachine/issues/123 states, known_content_type is independent from content_types_accepted.

This is rather confusing, and it doesn't have an obvious benefit: why/how can the resource know more content-types than it accepts and handles?

Proposed resolution
Remove the known_content_type callback, and make the decision based on inspecting the output of content_types_accepted

The configured homepage for this repository is http://hyperrest.github.io/2013-06-10-http-hell-no/:

But that leads to

Proposal: Enable gh-pages for this repository. The content seems to be existing: https://github.com/for-GET/http-decision-diagram/tree/gh-pages

The URL then should be https://for-get.github.io/http-decision-diagram/

it is not only the server that can benefit from an FSM to decide the HTTP response flow,
but also the client and the cache proxy (a version is already in master branch based on @darrelmiller's versions)

trigger: http://blog.safaribooksonline.com/2013/05/31/rest-from-a-client-perspective/