For notes on REST APIs during the 2017 Alkmaar SEC meeting.

Items to revisit / refine:

• 'options' endpoint - body contents; SI provided initial draft version
• add note about branching not supported in current version of spec in overview notes
• global style
  • date/time format for REST - in query params - use 'clean' ISO8601 expanded format (also no 'Z')
  • revisit Location versus Content-location - BL / HF - use Location at least
  • global use of singular attribute in REST API
    • EHR URIs stay in their current form - designed to follow RM attributes names
    • provide a EHR URI resolver end-point under /
• /ehr
  • make subject_id more obvious as an optional param
• For calls returning sets / lists of things, need a 'db cursor' equivalent, which enables paging of results.
• text style changes
  • Get xxxxx version by id => get xxx by version id in documentation - was changed in EHR status
  • 204 error messages - state in positive form ; check others.
• check Update methods with version_id as a param - use only Match-If: {prec-version-id}
• Response 401 body in COMPOSITION POST

REST API publishing:

• try to enable internal links inside the spec - probably requires publication shell script to process into proper URLs.

Validation errors of a COMPOSITION from a POST needs a structure defined in BASE - Pablo has suggestions

class ErrorAccumulator
	errors : List<Error>
end

class Error
    location: Integer
    code: String
	text: DV_TEXT
end

Also define set of standard error codes / tokens in openEHR similar to ADL V-codes which are defined in the AOM2 spec - See Veratech validation errors.

Other Qs:

• version branching - need one day to specify semantics of AQL when there are branches present.

DAY 2

copy header commit audit from Heath's email

BL: to commit lifecycle state in audit, want to be able to specify code or rubric string; 

need to add a copy of the lifecycle states from XML terminology to the REST overview documentation commit audit header.

Where are Uids supplied from?

Question of whether Composition uids should be supplied from the client side;

Reason to supply Uid is when it is to be used in FOLDERs referencing the COMPOSITION - this enables a single Contribution to contain FOLDER updates in the same CONTRIBUTION as COMPOSITION.

POST doesn't allow Uid; can use PUT without match-if header, and a supplied Uid.

Split PUT Composition into 2 calls - one with Version Uid supplied; other without; simplify documentation.

If Version Uid is supplied: it should all be there, including version = 1

Last updated

Heath: add a last-updated: date_time header (formatted according to HTTP rules, i.e. no milliseconds). For all GETs; ?POST response as well.