|
67 | 67 | <tr> |
68 | 68 | <td>4.1</td> |
69 | 69 | <td><a href="https://specifications.openehr.org/tickets/SPECITS-66" target="_blank" rel="noopener">SPECITS-66</a>: |
70 | | - Migrate REST API specs to openAPI format</td> |
| 70 | + Migrate REST API specs to OpenAPI Specification</td> |
71 | 71 | <td>S Iancu</td> |
72 | 72 | <td>14 Nov 2022</td> |
73 | 73 | </tr> |
@@ -276,16 +276,17 @@ tags: |
276 | 276 | | `uid_based_id` | An abstract identifier: it can take a form of an OBJECT_VERSION_ID identifier taken from VERSION.uid.value (i.e. a `version_uid`), or a form of a HIER_OBJECT_ID identifier taken from VERSIONED_OBJECT.uid.value (i.e. a `versioned_object_uid`). | |
277 | 277 | | `preceding_version_uid` | The value of a previous VERSION unique identifier, used usually for PUT or DELETE methods (e.g. 8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1) | |
278 | 278 | | `version_at_time` | Time specifier used to retrieve the VERSION at a given time; the value is in the extended ISO 8601 format (e.g. 2015-01-20T19:30:22.765+01:00) | |
279 | | -
|
| 279 | + <br> |
280 | 280 |
|
281 | 281 | ### OpenAPI Specification files |
282 | 282 |
|
283 | 283 | This openEHR REST specifications can be downloaded as YAML files in [OpenAPI Specification 3.0](https://spec.openapis.org/oas/v3.0.3) format. |
284 | 284 |
|
285 | 285 | For each API there are two flavours provided: |
286 | | - - a file optimized for code generators, with the file name having the `-codegen.openapi.yaml`; this file can be used with tools like [OpenAPI Generator](https://github.com/openapitools/openapi-generator), or [Swagger codegen](https://github.com/swagger-api/swagger-codegen), |
287 | | - - a file optimized for data validation, with the file name having the `-codegen.openapi.yaml`; this file can be used by (mock-)servers or applications to validate openEHR request and response payloads. |
288 | | - The main difference between these files (aside of schema model names) is that the codegen flavour is defining and using inheritance in model schemas, with the use of `allOf` property and discriminators (see [Polymorphism](https://spec.openapis.org/oas/v3.0.3#composition-and-inheritance-polymorphism)), whereas the validation variant is flattening all these requirements (each model contains all RM-inherited properties). |
| 286 | + - a file optimized for code generators, with the file name having the `-codegen.openapi.yaml` suffix; this file can be used with tools like [OpenAPI Generator](https://github.com/openapitools/openapi-generator), or [Swagger codegen](https://github.com/swagger-api/swagger-codegen), |
| 287 | + - a file optimized for data validation, with the file name having the `-codegen.openapi.yaml` suffix; this file can be used by (mock-)servers or applications to validate openEHR request and response payloads. |
| 288 | +
|
| 289 | + The main difference between these files (aside of schema model names) is that the codegen flavour is defining and using inheritance in model schemas, with the use of `allOf` property and discriminators, whereas the validation variant is flattening all these requirements (each model contains all RM-inherited properties), and is using `oneOf` property to define union-types. See [Polymorphism](https://spec.openapis.org/oas/v3.0.3#composition-and-inheritance-polymorphism) specification. |
289 | 290 |
|
290 | 291 | The latest OpenAPI Specification files are available in GitHub at [openEHR/specifications-ITS-REST/computable/OAS](https://github.com/openEHR/specifications-ITS-REST/tree/master/computable/OAS). |
291 | 292 | - name: Requests_and_responses |
@@ -376,11 +377,10 @@ tags: |
376 | 377 |
|
377 | 378 | ## If-Match and accidental overwrites |
378 | 379 |
|
379 | | - This `If-Match` request header SHOULD be used by the clients to prevent accidental overwrites when multiple user |
380 | | - agents might be acting in parallel on the same resource. This is only required by a small set of resources of this specification, |
381 | | - as in most of the other cases the `preceding_version_uid` path segment is instead required in order to prevent such accidental overwrites. |
382 | | - In case a service receives this header, and the condition evaluates to `false`, it MUST respond with |
383 | | - HTTP status code `412 Precondition Failed` and return also latest `version_uid` in the `Location` and `ETag` response headers. |
| 380 | + The `If-Match` request header SHOULD be used by the clients to prevent accidental overwrites when multiple user |
| 381 | + agents might be acting in parallel on the same resource. This is only required by a small set of versioned resources of this specification. |
| 382 | + In case a service receives this header, and the condition evaluates to `false`, it MUST NOT perform the requested method and instead MUST respond with |
| 383 | + HTTP status code `412 Precondition Failed`, and SHOULD return also latest `version_uid` in the `Location` and `ETag` response headers. |
384 | 384 |
|
385 | 385 | Example: |
386 | 386 | ```http |
@@ -628,7 +628,7 @@ tags: |
628 | 628 | When resources representation is serialized as XML, the request payload as well as the result MUST be valid against [published XSDs](https://specifications.openehr.org/releases/ITS-XML/latest). |
629 | 629 |
|
630 | 630 | A client MAY use the header `Content-Type: application/xml` in the requests to specify the XML payload format. |
631 | | - If the service cannot process the request payload as XML format is not supported, it MUST respond with HTTP status code`415 Unsupported Media Type`. |
| 631 | + If the service cannot process the request payload as XML format is not supported, it MUST respond with HTTP status code `415 Unsupported Media Type`. |
632 | 632 |
|
633 | 633 | The client SHOULD use the `Accept: application/xml` request header in order to specify the expected XML response format. |
634 | 634 | If the service cannot fulfill this aspect of the request, it MUST respond with HTTP status code `406 Not Acceptable`. |
@@ -729,7 +729,7 @@ tags: |
729 | 729 | Current alternative formats might not be supported once they become obsolete or superseded by newer formats. |
730 | 730 |
|
731 | 731 | A client MAY use the header `Content-Type` in the requests to specify the simplified payload format. |
732 | | - If the service cannot process the request payload as the simplified format is not supported, it MUST respond with HTTP status code`415 Unsupported Media Type`. |
| 732 | + If the service cannot process the request payload as the simplified format is not supported, it MUST respond with HTTP status code `415 Unsupported Media Type`. |
733 | 733 |
|
734 | 734 | The client SHOULD use the `Accept` request header in order to specify the expected simplified response format. |
735 | 735 | If the service cannot fulfill this aspect of the request, it MUST respond with HTTP status code `406 Not Acceptable`. |
|
0 commit comments