REST API Specifications in OpenAPI format

Specifications ITS
,
1

I am investigating a rewrite of our current REST API Specification (now in Api-Blueprint format) as OpenAPI 3.1 or 3.0 format. Has anybody already done this and is willing to share it? then it will be helpful and highly appreciated - please contact me or respond here.

1 Like
2

Hi Sebastian, I think this is a great effort!
We have our CDRs api’s in OpenAPI 3.0, but they are from before the rest api was specced, so there will be differences. You can contact @Jelte for more info.
Btw do you know about stoplight.io studio? It’s a gui tool to create OpenAPI specs.

1 Like
3

Thanks Joost. Yes I knew about stoplight, great tool, but at this time I was looking more for content (api specs) rather then tooling; I will contact Jelte.

1 Like
4

Hi Sebastian,
I also think that it is a great initiative. We use Stoplight studio for our platform API documentations and use ReDoc for publishing them.

However, I think ReDoc does not fully support Openapi 3.1 now. Stoplight elements is another good option to publish the documents. I have tried it out but did not switch from ReDoc as we did not find any major advantage.

I am available to help if required.

regards

2 Likes
5

Hi,

Redoc and or elements (from stoplight) were on my radar. I tried also other alternatives, but these two looks better (Redoc reacher, elements nicer).
I will definitively contact you, but first we need to settle some goals/project from SEC-group perspective.

6

This is what I have created for the openEHR Toolkit to support the Definitions endpoints (since we store archetypes and templates)
openehr_toolkiit_definition_openapi2.json (8.3 KB)

The model schemas included are for the summaries of archetypes and templates, since templates are still in ADL we don’t have a schema for those (it would be a good idea to support AOM1.4 archetypes in JSON though).

7

Given the fact that in openEHR, the same set of APIs are used to manage all variations of templates and data instances, we may not be able to define a schema for apis dealing with individual artifacts (templates, compositions etc). We have to use examples to document this functionality.

I have converted a postman collection that we had made for testing EHRBase into OpenAPI. I can clean it up and share it for use as a starting point.

regards

2 Likes
8

can you please explain why?

9

I meant the request and response body schema, as these are different for each template. All the common elements like the headers, params can be defined.

1 Like
10

What I would really like as a CDR feature is to generate endpoints for each template, where the schema (template) is ‘defined’ in OpenAPI. This would seriously lower the bar for new developers to start working with openEHR. Would make it even easier than FHIR I hope. @NeoEHR is quite far along this task, but he needs funding to got further.

1 Like
11

Hi @joostholslag,

I think this is already achieved to some extend by STRUCTURED and FLAT formats.

Maybe I understand OpenAPI not well enough and this is a stupid question, but is there a reason why this cannot be defined based on WebTemplate and STRUCTURED format?

12

There is no such thing.

To explain the context: the effort here is to have a new ITS artefact. An openAPI based specification of REST API, which can be fed into document generators, but (more importantly from an ITS pov) also to code generators. This gives openEHR community access to contract-first approach to our REST API. As in, you can get the output of this work, generate both documentation and C#/Java/… code and use that to adopt your existing systems to openEHR, or implement one from scratch, fulfilling the contract of our REST API.

Now, the “clinical APIs” as we call them in Ocean (and others do the same elsewhere I guess), are focused on level 2 of two level modelling, and specifying them based on OpenAPI, to achieve the same benefits I explained above, is a different task. This was discussed in the SEC meeting and my comment was that it would make a good downstream work, once we have the initial output for REST API.

I cannot see any reason for not doing the auto-generation work based on STRUCTURED or FLAT or webtemplate etc formats for the clinical APIs, but then the formalism used to derive the auto generation would not have the ecosystem that OpenAPI has behind it. I’d see that as a downside, but there would be upsides as well, since every re-use of a generic tech comes with its loss of information, and doing what you’re suggesting may offer benefits over using OpenAPI for it. I’d say this scenario has some problems by nature though, which I outlined in my discussion with Erik here:

3 Likes
13

Hi,
I created a doodle page to find out the best moment to meet next week (preferably) with more people.
The link is here at Doodle. Anybody who would like to be involved (help) or are seriously interested in these specifications are welcome to join.
Please respond in the following few days so that we can pick the best date.

14

A one-off partial generation to help get the first version of an OpenAPI file could still be useful - even if then followed by manual only editing. Depends on how hard that is to build though :wink:

15

I think that’s pretty much what @sebastian.iancu did.

16

This is possible at an implementation level documentation as templates are implementation specific.

openEHR REST specification does not cover template/composition definitions as they are implementation dependent. So we can define the general pattern in this spec and leave the implications to make it more specific for their documentation.

Regards

1 Like
17

My question is rather the following: how would the payload of an HTTP request differ in openAPI compared to the structured format?

{
    "klinische_frailty-skala": {
        "category": [
            {
                "|code": "433",
                "|terminology": "openehr",
                "|value": "event"
            }
        ],
        "context": [
            {
                "status": [
                    {
                        "|code": "at0010",
                        "|value": "registriert",
                        "|terminology": "local"
                    }
                ],
                "kategorie": [
                    "Lorem ipsum"
                ],
                "start_time": [
                    "2022-02-03T04:05:06"
                ],
                "setting": [
                    {
                        "|terminology": "openehr",
                        "|value": "home",
                        "|code": "225"
                    }
                ],
                "_end_time": [
                    "2022-02-03T04:05:06"
                ],
                "_health_care_facility": [
                    {
                        "|name": "DOE, John"
                    }
                ]
            }
        ],

To my understanding, openAPI could provide a payload definition that could exactly look like the STRUCTURED format. It might not be the best approach (in our openEHR SDK, we have also a DTO model which looks different from STRUCTURED), but I’m wondering if I’m still missing the point. I can imagine there to be custom made APIs that suite different needs of developers, but I think these will be manually curated with some auto-generation to support the work.

18

The schema of an OPT is not different for each template. OPT is one specific format with one schema. I’m not sure I’m following.

19

Pablo, what I think Dileep refers is related to what Birger asks.

There are two ways of creating data discussed here:

  1. submit a standard COMPOSITION
  2. submit a dataset in a STRUCTURED or FLAT format

The structure of the second way is derived from the underlying template, thus is different for each template - therefore we cannot publish a standard OpenAPI schema for the models - those have to be generated ad-hoc by tooling (sort of “Export as OpenAPI schema-yaml”, depending on the format used, STRUCTURED or FLAT).

So, to respond to Birger’s question, depending on the way you submit the data, you would need to have a different format, even though the content is semantically the same. Therefore the OpenAPI schema to validate such data should be different, or it should use ‘oneOf’ to validate both formats.

Our preference is to focus (for now) on the first way: the OpenAPI specification of the standard (canonical) COMPOSITION; later we’ll see about the other one - or hopefully tooling might want to address this issue.

2 Likes
20

Thanks @sebastian.iancu FLAT is not yet standardized and doesn’t have a schema AFAIK, I wouldn’t bother of even considering that format for the initial OpenAPI work. In fact I would go to JSON canonical only first. This “structured” neither exists, it’s just the canonical form named structured by some vendor.

If later other formats should be added, then I guess the schemas should be updated, but I would suggest to create a different definition file instead of putting different schemas inside the same definition. Of course if we can externalize the schemas it’s better, but for having “alternative” schemas, it’s better to have also separated definitions. In the long run it will get complicated to support alternative schemas under the same definition. It’s complex enough supporting two schemas for the canonical format in JSON and XML in the same OpenAPI definition.