Thanks @pablo, good initiative and exploration of a potential API for demographics.
While I don’t want to directly discourage you, and neither criticize the API without presenting alternatives, I still must say that this is (at this time) Atomik.app variant of the API for demographics. As @erik.sundvall mentioned, there were already discussions going on about the openEHR API for demographics within the SEC, results being summarized here.
There were also numerous discussions in SEC, occasions and topics on discourse over the last X years where I showed and explained Code24 experience with such API, which I’m hoping will be also taken in considerations in the official openEHR API specs.
Besides the naming in the url issue, i.e. demographic vs registry (see also Demographic model improvements), I see a few other issues to be tackled:
- missing the contribution endpoint (although in your design I think everything is still versioned)
- the PARTY_RELATIONSHIP should not be that weak on the ‘source’ side - i.e. every time a PARTY gets a change in their direct-relationship list it should end up in a new version; we discussed the SEC that reverse_relationship should become a function instead of an attribute, so that it can be computed/calculated instead of persisted
- PARTY_RELATIONSHIP should not be versioned (but is a LOCATABLE); we should have anyways an endpoint to GET them, but the creation/update is always in relation with their source
- ROLE should not be weak, should be versioned and also needs to be supported by the API at a separate endpoint
- an ACTOR contains a reference to a ROLE (via PARTY_REF), but not the ROLE itself so we should not make it part of the ACTOR REST resource
- an ACTOR is an abstract type, I suggested in SEC to have API endpoints for concrete types (PERSON, GROUP, etc)
- you mentioned RM 1.0.3 specs, but I think we discussed in SEC that we should focus on a REST spec for RM 1.1
- we’ll need a SYSTEM concept also
- we’ll also need support in AQL and on /query endpoint