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 17235: 6.4 baseURL/sectionpath
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 17375: separate the general RESTful pattern use from the hData specific features
Issue 17376: Enable the use of version-aware resource URLs
Issue 17377: Alternate content negotiation
Issue 17378: Validation service
Issue 17379: Simple search
Issue 17380: Intermediaries Consideration
Issue 17381: Metadata Communication
Issue 17382: no clear conformance point
Issue 17383: Comments on Section
Issue 17384: Comments on Section 3
Issue 17385: Comments on Section 6
Issue 17386: Pattern for reliability
Issue 17387: Comments on Section 8
Issue 17388: Comments on Section 9
Issue 17566: Need clarificaton for server response to client request using the Max-Forwards header field
Issue 17579: Inconsistent spelling for extensionId in parameter list for 6.2.2
Issue 18133: mime type for format parameter (text/xml vs. xml)
Issue 18134: Represent DELETE in Atom: XML Fragment in Atom:Content
Issue 18135: Content override in two party update
Issue 18136: Atom feed link:rel needs to be version specific
Issue 18137: search extensions (include as non-normative examples)
Issue 18138: subscription push
Issue 18139: Conformance statement
Issue 18221: Revise current (20121004) JSON representation of Atom feed and data in section 6.1.2
Issue 18222: discuss impact of deletion of resources/SectionDocuments onto the Section level Atom feed/JSON bundle to section 6.4.4
Issue 18227: Change 6.5.3 to allow PUT creation of new documents to allow the client to suggest location. Same semantics as 6.4.2.2
Issue 18290: Create a subsection in section 6.1.2 to identify forbidden keywords in paths for URLs
Issue 18291: Create a paragraph in section 6.5 clarifying how resource URL paths are constructed
Issue 18316: security negotiation through the use of custom HTTP 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

6.4.1 GET  This operation MUST return an Atom 1.0 compliant feed of all section documents and child sections contained in this section.
Status Code: 200
 
The implied requirement here is following:
If baseURL does not exist or no sectionpath of name sectionpath exists, the implementation MUST (SHOULD) 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.

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.

The specification as it is describes a particular pattern of use
that includes
aspects that are specific to hData. It would help us greatly to separate the
general RESTful pattern use from the hData specific features; this way, we could
reference the specification directly and it would be clear how we
could conform to it.

Issue clarified – section 6.1.3 will need to be revised

Most of the changes requested in this section apply to 6.5 of the
hData specification.
FHIR will need to be able to access different versions of a resource.
To enable this most
effectively, the spec should support the following URL extensions on
SectionDocuments
for GET, PUT, and POST operations:


(resourceURL) = (baseURL)/(sectionPath)/(sectionDocument)
(versionAwareResourceURL) = (resource)/history/(version-id)


where (version-id) is any unique string. Also, a GET on the (resourceURL) should
return the representation of the resource in the HTTP body, a status
code of 200, and
a Content-Location header containing the (versionAwareResourceURL) of
the current
version of that resource.


If the resource was deleted with a DELETE, the service SHOULD return a
HTTP status
code 410, with no body. However it MAY return a 404 as alternative.


To enable safe updates, the following process MUST be used:


• The client reads obtains the representation of the current version
by performing a GET
on the (resourceURL). This contains the reference to (versionAwareResourceURL).
• The client makes the necessary changes to the state.
• The client MUST then PUT the updates representation to the
(resourceURL) and quote the versionAwareResourceURL in the Content-Location
header of the PUT operation.
• If the (versionAwareResourceURL) provided by the client is the
current version, the
server accepts the representation and persists the change, and returns a HTTP
response with
• a status code of 202 ok,
• a Content-Location header with the (versionAwareResourceURL) of the new


version, and
• the representation of the new version of the resource in the
• If the (versionAwareResourceURL) represents no longer the current version, the
server MUST return a HTTP response with status code 412, a Content-Location
header with the new (versionAwareResourceURL), and a representation of
the latest
version of the resource.

Throughout section 6. of the hData spec, the server should accept the
following HTTP
query string to perform alternate media type negotiation:


(URL)?format=(mediaType)


where (mediaType) MUST be a valid Internet Media type. This explicit content
negotiation takes precedence over the Accept-Header negotiation. The
reason why this
is needed is the unreliable support of the Accept-Header mechanism in
clients, particularly
in older development stacks. While we strongly encourage adoption of
the content negotiation
framework per the HTTP specification, we wish to be as inclusive as possible

Similar to the version-aware resource structure, the following URL for
sectionDocuments is reserved:


(baseURL)/(sectionPath)/(sectionDocument)/validate/


This allows a client to ask the server whether the attached POSTed
content would be
acceptable as a PUT. By this means that client can
(a) validate business logic during testing concerning correct content
(b) implement a lite two-phase commit alternative that reduces the
chance of partial success of multi-resource operations.


The second functionality overlaps a little with existing functionality
around safe commit,
though what is there now solves a different problem. From the point of
view of FHIR, the
first is at least as important: a real world way to test content
without only having to rely
on claims.

To support simple searches over Sections and the entire record, for
the section 6.2 and
6.4, the following URL structure is reserved:


5.1. (baseURL)/search?(queryParameter)


This allows a search over the entire record. The (queryParameter) can
be arbitrary,
but it is RECOMMENDED to use HTTP form-encoding style key/value parameters.
The server returns the results of the query in the form of an Atom
feed, with each Entry
representing a search result.


5.2. (baseURL)/(sectionPath)/search?(queryParameter)


The semantics for this query are identical to the one in 4.1., but the
scope is limited to
the section described by the sectionPath.

The HTTP protocol may be routed through an HTTP proxy such as squid.
Such proxies are transparent to the applications, though implementors
should be alert to the effects of rogue caching.


Interface engines may also be placed between the consumer and the
provider; these differ from proxies because they actively alter the
content and/or destination of the HTTP exchange and are not bound the
rules that apply to HTTP proxies. Such agents are allowed, but must
mark the http header to assist with troubleshooting.


Any agent that modifies an HTTP request or Response content other than
under the rules for HTTP proxie must add a stamp to the HTTP headers
like this:


  request-modified-[identity]: [purpose]
  response-modified-[identity]: [purpose]


The identity must a single token defined by the administrator of the
agent that will sufficiently identify the agent in the context of use.
The header must specify the agents purpose in modifying the content.
End point systems must not use this header for any purpose; it's aim
is to assist with system troubleshooting.


."

Section 6.2.5 and 6.3 can be combined into a single way to query for
metadata about
the service. The additional HTTP headers created in 6.2.5 are
problematic for some
clients and/or servers to implement. As such the OPTION operation on
the (baseURL)
could return a body with a XML document instead, which contains the information
contained in the 6.2.5. headers, as well at the root.xml manifest.
This would reduce the
number of roundtrips significantly. There should also be a way to
access this information
without using the OPTIONS command to enable the same information to be available
via a <a href=""> link in a web page.

There is no clear conformance point but the understatement made by the use of the RFC2119. I propose to rename section 4 "Conformance point" and to add "Implementations must support the entire mapping" before the description of keywords.

 How is this wpecification supposed to evolve wrt the version of OMG's RLUS and HL7's RLUS? I believe this should be a bit explained in section 1.
- Complex operations as well as Security need to be also introduced in this section.
- Last paragraph: add reference [12] when speaking of the OMG RLUS PIM.

In the paragraph "hData REST Binding for RLUS": "... HRF specification is access..." -> is accessed
- The paragraph "Semantic signifier" speaks about "The UML diagram below..." while there is no UML diagram. If you decided to add such a UML diagram, the matching XMI would be necessary.

The Get/Put/Delete/Post subsection are not allways listed in the same order, which doesn't ease the reading and the finding of information.
- Section 6.2.5: add a reference to the section 8 which is also speaking about this point.
- Section 6.4.1: ", is RECOMMENDED" -> ", it is RECOMMENDED"

Section 7.1: in which way this pattern is "reliable"? A clear explanation of which risks are covered is needed here.

Section 8.1 - 2nd paragraph: sentence not parsable: "If the custom security mechanism The URIs..."
- Bullet 2: should be "URI or none" on account of the HTTP Transport Security
- Bullet 5: "State Diagram": what is the format of this UML state diagram? XMI?
- Section 8.3 - last sentence: which "template" are you speaking of? 
- Section 8.4 and 8.5: these sections should be noted as informative or non-normative (in their title)

This section must be noted as non-normative (in the title)
- Section 9.2 - in the table: replace "(version 1.0.1...)" with the reference [12]

Section 6.2.5 states "client MUST NOT use the Max-Forward header when requesting the security mechanisms for a given HDR" but no action is defined for the server.


If Max-Forwards field is truly not permitted on the OPTION operation then recommend adding expected the server action. Suggest to return a 403 Forbidden status code with optional message "Request cannot include Max-Forwards header field".


References:
Max-forwards usage:
http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.2


HTTP status codes
http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

6.2.2 POST ­ Parameters:extensionID, path, name


But the body of the section defines the 'extensionId' parameter with different spelling.


This should be consistent with created sub-section as defined in 6.4.2.1 which uses extensionId in all occurrences.

extensionID should be corrected and renamed to "extensionId".

mime type for format parameter (text/xml vs. xml)
        - exception for xml and json
        - MUST accept full MIME types

Represent DELETE in Atom: XML Fragment in Atom:Content
        - Needs to be for 410 resources, not for 404
        

 Describe obligations and error codes around create/updates
        - Server can deny update request when update is incorrect
        - (HTTP PUT)
        - This may be best suited to be resolved at the FHIR specification level

- MUST support version specific retrieval of current version
        - MAY support version specific retrieval of older version

- $INCLUDE 
        - others

- client pushes feed
        - enable "bulk" update
        - POST to Section (see 6.4.2.2)

- use baseURL/metadata to allow service information
        - provide current baseURL/conf as non-normative example

 revise current (20121004) JSON representation of Atom feed and data in section 6.1.2, and incorporate lessons-learned from FHIR implementation

discuss impact of deletion of resources/SectionDocuments onto the Section level Atom feed/JSON bundle to section 6.4.4

Change 6.5.3 to allow PUT creation of new documents to allow the client to suggest location. Same semantics as 6.4.2.2, if conflict return 409

Create a subsection in section 6.1.2 to identify forbidden keywords in paths for URLs

Create a paragraph in section 6.5 clarifying how resource URL paths are constructed

We had identified a potential issue for a future hData RTF regarding the security negotiation through the use of custom HTTP headers. A future version of hData should use the WWW-Authenticate header instead of any X-hdata-* custom headers.