Issues for Mailing list of the hData REST Binding for RLUS 1.0 (hData) Finalization Task Force

List of issues (green=resolved, yellow=pending Board vote, red=unresolved)

List options: All ; Open Issues only; or Closed Issues only

Issue 16914: RESTful vs. REST
Issue 16915: Lack of a Normative References section
Issue 16916: Section 3, 3rd definition: typo “is access”
Issue 16917: 6.1.1 penultimate sentence, typo “this documents”
Issue 16918: 7.1 line 2: “This pattern may be combined” – unclear what it may be combined with.
Issue 16919: 8.5 first line type RECOMMEDED
Issue 16920: Annex A: reference [1] is normative for this specification but there is no indication of how it can be obatined
Issue 17233: 6.2 Operations on the Base URL
Issue 17234: 6.3 baseURL/root.xml
Issue 17236: GET operation on baseURL/root.xml needs explicit MUST in the requirement
Issue 17237: OPTIONS operation on not-existing baseURL should return 404 status code
Issue 17238: GET operation on non-existing baseURL or sectionpath SHOULD return 404 status code
Issue 17239: DELETE on invalid or not-existing documentname URL should return 404 status code
Issue 17271: Missing action in 6.4.2.2 when not including metadata
Issue 17287: Creating sub-secton incorrectly describes updating the root document
Issue 17308: Wrong target context in 6.5.4 - change 'section' to 'document'
Issue 17313: Minor deletion or rewrite to PUT operation wording
Issue 17348: Section 6.5.1 should specify allowing negotiation through HTTP Accept headers

Issue 16914: RESTful vs. REST (hdata-ftf)

Throughout the text of the RFC document, you refer to "RESTful" while the cover page uses the term "REST" in the title of the RFC.  Please reconcile the use of these terms throughout the document.

Lack  of a Normative References section e.g. including Atom and other documents referenced as being required for an implementation

Section 3, 3rd definition: typo “is access”

6.1.1 penultimate sentence, typo “this documents”

7.1 line 2: “This pattern may be combined” – unclear what it may be combined with.

8.5 first line type RECOMMEDED

Annex A: reference [1] is normative for this specification but there is no indication of how it can be obatined

6.2.5 OPTIONS
OPTIONS on HDR baseURL MUST return 200 status
 
The implied requirement here is following:
If there is no HDR at the base URL, the server SHOULD return a 404 - Not found status code.
 
This would then be consistent with requirement in section 6.2.1 for GET operation.

6.3.1 GET
 
This operation returns an XML representation of the current root document, as defined by the HRF specification.
 
Status Code: 200
 
It can be inferred from this requirement that this is an implied “SHALL” or “MUST” mandatory requirement not an implied SHOULD/RECOMMENDED.
This implies the HTTP response contentType is text/xml or application/xml and the target namespace in the returned document ishttp://projecthdata.org/hdata/schemas/2009/06/core as defined by the HRF spec.
Likewise, not defined if the baseURL does not exist, which should return 404 status code as done with similar HTTP operations.
 
Recommend rewriting this requirement as follows:
6.3.1 GET
 
This operation MUST return an XML representation of the current root document, as defined by the HRF specification.
If there is no HDR at the base URL, the server SHOULD return a 404 - Not found status code.
 
Status Code: 200, 404

The requirements reads as "This operation returns an XML representation of the current root document, as defined by the HRF specification."


It can be inferred from this requirement that this is an implied “SHALL” or “MUST” mandatory requirement not an implied SHOULD/RECOMMENDED.


Likewise, not defined if the baseURL does not exist, which should return 404 status code as done with similar HTTP operations. This would then be consistent with requirement in section 6.2.


Revised requirement:


This operation MUST return an XML representation of the current root document, as defined by the HRF specification.
If there is no HDR at the base URL, the server SHOULD return a 404 - Not found status code.

The requirements reads as "OPTIONS on HDR baseURL MUST return 200 status".


The implied requirement is the following which should be appended to this requirement:


If there is no HDR at the base URL, the server SHOULD return a 404 - Not found status code.

This would then be consistent with requirement in section 6.2.1 for the GET operation.

6.4.1 defines a GET with a 200 for success but doesn't address the not found case as defined in other GET operations (e.g. 6.2.1 and 6.5.1)


The implied requirement here is the following, which should be added to the section:


If baseURL does not exist or no sectionpath of name sectionpath exists, the implementation SHOULD (or MUST) return a HTTP status code 404.

This would then be consistent with section 6.5.1 for an invalid/non-existing documentname in the URL

Context: 6.5.4 DELETE baseURL/sectionpath/documentname


The implied requirement here is the following, which should be appended to the section to make it consistent with 6.4.4 and 6.5.1:

If baseURL, sectionpath, or target document name does NOT exist, the implementation SHOULD return a 404 - Not found HTTP status code.

Section 6.4.2.2 (Adding new document) describes the case when including metadata in POST operation using 
"multipart/form-data", however, it does not describe when not including metadata.


Here's text for the implied requirement:


If POST does not include metadata then MUST POST with a Content Type conforming to the media type of the section. The body of the POST MUST contain the document of the new document. Document metadata in this case MUST be computed from the new document.


This text or something like it must be inserted in this context:
"It is to be treated as informational, since the service MUST compute the valid new metadata based on the requirements found in the HRF specification <INSERT HERE>
The content media type MUST conform..."

Context:
 6.4 baseURL/sectionpath
 6.4.2.1 Add new section


OLD text: When creating the section resource, the server MUST update the root document: in the node of the parent section a new child node must be inserted.


This is the same text copied verbatim from section 6.2.2 which describes creating a new Section at the root of the document: "when creating the section resource, the server MUST update the root document: in the node of the parent section a new child node must be inserted" but in the context of creating a sub-section this is incorrect.


The correct rewording should be:

NEW: When creating the sub-section resource, the server MUST update the Atom 1.0 [3] compliant feed for the parent section: a new child node must be inserted as an entry in the Atom content with a link to the new section.

Context:
6.5 baseURL/sectionpath/documentname
6.5.4 DELETE


Text: Future requests to the *section* URL MAY return a status code of 410, unless the record is restored.


"section" here should be changed to "document" because that is the context here.

Also for clarification does future request mean only GET requests or does it include any/all operations on the document { POST, PUT, DELETE, etc. }

Context:
 6.5 baseURL/sectionpath/documentname
 6.5.2 PUT


The text "If the request is successful, the *new* section document MUST show up in the document feed for the section" is not applicable for a document update since it's not a new document but an update.


This is text verbatim from section 6.4.2.2 [Add new document].


The text could be deleted or reworded to something like this:

"If the request is successful, the *updated* section document MUST [continue to] show up in the document feed for the section".

Section 6.5.1 should specify that content negotiation through HTTP Accept headers is possible, and indicate how this interacts with the metadata specified in the HL7 spec.