New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Consider relaxing some MUSTs #2
Comments
Every MUST is one less opportunity for implementations to be compliant and incompatible. Please keep the MUST. |
The MUST will not be a barrier to compliant implementations because they will do what the spec says. It will also not be a barrier to non-compliant implementations because they won't do what the spec says. 👍 for keeping the MUST |
note that each MUST is a promise forever. no future mod, update, or bug fix would be allowed if it ran counter to an existing MUST. aim for SHOULD and MAY, limit MUST to bare minimum. adding MUSTs puts limits on an unknown future - that's rarely a smart idea. to encourage implementations to follow you specs closely it is common to use the following in your documentation: An implementation is not compliant if it fails to satisfy one or more of the MUST or REQUIRED level requirements. An implementation that satisfies all the MUST or REQUIRED level and all the SHOULD level requirements is said to be "unconditionally compliant"; one that satisfies all the MUST level requirements but not all the SHOULD level requirements is said to be "conditionally compliant." |
"adding MUSTs puts limits on an unknown future - that's rarely a smart idea." No, adding MUSTs make the lives of implementors easier and eliminates opportunities for incompatible implementations. That unknown future is properly handled in a protocol through versioning and extension mechanisms that allow entirely optional additional behavior, not through a proliferation of MAYs. For example, look at how few MAYs are in RFC2616 and how most of them relate to client behavior in the face of MUST and SHOULD behaviors on the server. That is the result of careful protocol design and painful experience. Postel's Law in action: http://en.wikipedia.org/wiki/Robustness_principle |
My count of RFC2119 words in RFC2616 (including initial description of the words):
There is no incentive to build servers that screw up people's data. You don't need to beat everyone over the head w/ MUSTs. Just help them out w/ guidance w/ SHOULD (to stay compliant) and advice w/ MAY. And since you're ref'ing RFC2616, this section on the use of If-Match on PUT should be considered: |
Good point, mamund. One SHOULD in RFC2616 is relevant here: I would tend to take advantage of this SHOULD when designing an API that may be used by tens of thousands of developers, many with no previous experience using a ReST API. If all they are doing is trying to accomplish a task like sending a text message, I am going to return a response of a default representation even if they don't send an accept header with application/json. If given the choice of rigid adherence to a standard versus API ease of use, I will choose the latter. A standard that gives some flexibility with SHOULD's is one that I am more likely actually follow. |
For this specific example I would suggest keeping it regulated. Considering that the content type has been changed now and certain clients might ask for application/json, I propose modifying the requirements as follows:
|
"If the request's Accept header permits..." : the client controls this string, not the server. and clients can add whatever media types they wish whether servers understand them or not. what you might be trying to say is something like this: "If the server can represent as resource in the Personally, I think this is over-constraining. I see no reason to over-ride the HTTP spec which uses the SHOULD word (not MUST) in directing servers on how to respond to the |
json-api is a protocol defined on top of http. by definition, it must if you just say "do whatever http says you can", then json-api is
|
Constraining the application-level protocol (json API) is great. |
making specific choices about which http mechanisms to use and how exactly
|
What I'm trying to say: If the server decides to reply with a json-api repsonse, and the accept header includes |
@rkh: aahhh! then i'd say just that. IOW, don't write it in terms of how to use HTTP features, write it as you just did, in terms of how to use JSON API features. |
FWIW, my advice is to not author a new protocol on top of the HTTP protocol. Instead focus on authoring a new media type that can work with one or more protocols. there is huge oppty here to create a single format that works in many places now and in the future. frankly, i'd like to see this message model appear not just in HTTP, but also CoAP and MQTT going forward. if you spend a great deal of time fiddling w/ HTTP details and baking them into this spec, you'll be forever tied to that one protocol and will be increasing the chances of running afoul of mis-interpretations at the network-level and even possible changes at the network level over time. just my $0.02. Cheers. |
@mamund it's already constrained to the HTTP protocol by taking advantage of HTTP verbs and HTTP headers, so your idea might be overly optimistic. I think it might be interesting as a proof of concept to use the JSON API media type over another protocol like WebSockets, but you'd have to invent new vocabulary to do that. |
Added jsonapi-converter link to the list of client libraries removes trailing comma from JSON object Update index.md Add link to JsonApiParser library. Include JSONAPI::Utils gem in the list of implementations Include JSONAPI::Utils gem in the list of implementations json-api#2 Remove redundant gem name in the server libraries list Add Morpheus for Java client libraries updating from the upstream repository added the hypermedia.cainosullivan.com to the examples
One from HN:
https://news.ycombinator.com/item?id=5656097
The text was updated successfully, but these errors were encountered: