REST API Specifications in OpenAPI format

Specifications ITS
,
21

Sorry again for being the dummy here, but what is the advantage of having a generic openAPI representation of canonical JSON? Will this allow to automatically derive a RM representation in any programming language with an openAPI generator? In this case: sounds useful for some cases but this is typically not a problem for us.

I thought this is mainly about taking templates and helping to derive an (open)API which can then be used to generate specific classes in any programming language to make openEHR client development much easier. Our SDK is limited to usage in Java and a generic approach to create classes which can be consumed by the API in Python, Ruby, C# etc. sounds like the killer feature.

So thanks for explaining, is this a fair summary?

1 Like
22

Sure you are right, but if you would like to have those TDO/TDS then you’ll end up with template dependent schema. See also Seref’s post here.

noted! That was also my suggestion in latest SEC meeting.

perhaps we can still have a generic schema?! - to be discussed later…

The thing is that RM canonical is not always suitable to be a REST-API resource (think for instance on EHR vs EHRSummary, or the issue with some RM-invariants). And we cannot leave it open-choice to clients; we need to be a bit more strict and specifying it. On the way we could also choose to optimize some of REST resources (using composition, or derivation) over their RM counterpart, but that still has to be specified as OpenAPI schema. If all these are done, then implementers may use various tools to generate code in the language of their preference as you also suggested - and my hope is openEHR CDRs will use and extend this OpenAPI spec with their own additions (extra endpoints, headers, statuses, etc) in a very easy and consistent way, while also having their own rendering styling and branding.

That’s all valid and important enough to have, but I would say not right now - rather as a second stage. In my opinion it is more important (and doable) right now to have a better and computable specifications for our REST. In any case, these are all valid points (goals) to discuss in a meeting.

I think it is something that we must have specified - it is not really an optional aspect.

23

OpenAPI could work if you have one content-type for each payload schema for the same endpoint, for instance if we can identify canonical json, canonical xml, flat json, flat xml, etc. etc. canonical yaml??? with one content-type for each and one schema for each, that could work. But! this could generate a maintenance hell very quickly if not done correctly, we need to figure out how to work with multiple content types and schemas and what’s the best structure for the OpenAPI spec in this scenario, that is why I think we need to focus just on canonical JSON then add other formats, so we have one working spec and in the process we can learn how to deal with multiple formats and the maintenance issue.

Sorry I didn’t got that in the meeting.

I think an official flat format should have it’s own specific schema, though I’m not sure what a “generic” schema is, is that an schema with some elements defined and other elements open?

Canonical JSON is kind of the de facto format for the REST API spec. I don’t think it’s about code generation or anything, it just about supporting the default format in the OpenAPI spec then add other formats. Right now only canonical JSON and canonical XML have formal schemas in openEHR (part of the spec). Other formats are not yet part of the spec, so IMO we should put effort on have a complete OpenAPI spec with what are current official formats for openEHR, not community/vendor ad-hoc formats. Though, when those are formalized and part of the spec, they should have their own OpenAPI spec schema too.

I don’t think that is the focus of this task. Having an OpenAPI spec allows to generate/update documentation on the fly and that doc to be executable on top of an implementation to facilitate testing APIs. There are no templates involved in that, it just makes the maintenance of the REST API spec easier/faster. That’s kind of a first goal. Then, from that spec, it is possible to generate code as a byproduct, some might see value on that, though it is neither the main goal IMO. Another byproduct would be to generate test cases from existing metadata/data, like templates, and use that for conformance testing, and that might be related with what you mentioned, and would be of my special interest, but it’s not the main goal either, just something we might be able to do if we can release an official OpenAPI spec.

@sebastian.iancu when I mention canonical JSON, though I’m referring to the current RM schemas, in the context of the REST API those canonical JSON schemas should be the relaxed ones not the RM schemas. The relaxed ones should be derived from classes denoted in the Service Model specification, as the serialized form of instances of those classes.

Exactly, JSON is kind of the current de facto format for the REST spec, not an optional thing.

2 Likes
24

In the meanwhile - as status update, we are getting closer to Release 1.0.3 of our specification, based on OpenAPI.

The current state can be seen at: APIs Overview openEHR specs.
Feedback is appreciated!

3 Likes