SEC Meeting Alkmaar 2017 - REST APIs notes page

Owned by Thomas Beale
Last updated: 31-Aug-2017

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.


DAY 3

discussions about versioning definitions

/definition/template and /definition/query should include either a semver identifier or an openehr version identifier - more requirements should be gather here on how vendors are dealing currently with versioning  or proposals on this topic.

Contribution Commit

Uid can be provided by client, but if not unique, the server will return an error

Committer id in the version audit is trusted as being correct due to client app authentication

Audit time field must be overwritten by the server.

Bostjan: prefers 'relaxed XSD' approach

Default Stored Queries

Add a standard stored query to get all comps of an ehr with parameters:
- time (context/start_time)
- template_id
- name (name/value)
+ paging
with a pre-defined order: desc time