PUT and POST on /ehr are slightly inconsistent on the way EHR_STATUS may be used in the request body, text needs to be corrected and consolidated.
ehr.apib: "If not supplied, a default EHR_STATUS with the following attributes SHOULD be used by the service" – if I read this correctly, it seems like a note to service implementors. I'm more in favour of API documentation being oriented towards API consumers, so this could perhaps be rephrased as "a default EHR_STATUS will be provided by the server:". This sentence occurs twice in the file.
I agree Matija but are there places where this ‘consumer-oriented’ language needs to be more precise or can we find ‘reverse’ phrasing for MUST, SHOULD etc
MUST/ SHALL / REQUIRED => will
"a default EHR_STATUS will be provided by the server:".
SHOULD / RECOMMENDED => should normally
"a default EHR_STATUS should normally be provided by the server:".
MAY / OPTIONAL => may optionally
"a default EHR_STATUS may optionally be provided by the server:".