From 7421d64edb47f8f5dd61b97756525cc26742f651 Mon Sep 17 00:00:00 2001 From: Christoph Beger Date: Thu, 13 Oct 2022 09:13:17 +0200 Subject: [PATCH 01/12] Streamline openapi descriptions --- schemas/top-api.yml | 249 ++++++++++++++++++++++++-------------------- 1 file changed, 135 insertions(+), 114 deletions(-) diff --git a/schemas/top-api.yml b/schemas/top-api.yml index 1709a5b..1769e3e 100644 --- a/schemas/top-api.yml +++ b/schemas/top-api.yml @@ -2,17 +2,20 @@ openapi: 3.0.0 info: title: TOP API version: 0.5.1 - description: API to manage phenotypes, repositories, ontologies and organisations + description: API to manage phenotypes, repositories, ontologies and organisations and to execute phenotypic queries. servers: + - url: https://top.imise.uni-leipzig.de/api + description: Public demo server. - url: http://localhost:8080 + description: Local development instance. - url: http://host.docker.internal:8080 - description: In case the server is running on the Docker host + description: In case the server is running on the Docker host. paths: /metadata: get: - summary: OpenAPI description of this API + summary: Get OpenAPI description of this API. operationId: getMetadata security: - BearerAuth: [] @@ -27,14 +30,14 @@ paths: /ping: get: - summary: Checks if the server is running + summary: Checks if the server is running. operationId: ping security: - BearerAuth: [] - BasicAuth: [] responses: 200: - description: Server is up and running + description: Server is up and running. default: $ref: "#/components/responses/UnexpectedError" @@ -47,7 +50,7 @@ paths: - BasicAuth: [] responses: 200: - description: Object holding statistics + description: Object holding statistics. content: application/json: schema: @@ -57,19 +60,19 @@ paths: /document: get: - summary: Searches for documents + summary: Searches for documents. operationId: getDocuments tags: - document parameters: - name: id in: query - description: Filter documents by their id. + description: Filter documents by ID. schema: type: string responses: 200: - description: List of documents + description: List of documents. content: application/json: schema: @@ -85,7 +88,7 @@ paths: parameters: - $ref: "#/components/parameters/include" get: - summary: Searches for organisations. Use the query parameters to filter the result. + summary: Search for organisations. Use the query parameters to filter the result. operationId: getOrganisations tags: - organisation @@ -98,7 +101,7 @@ paths: - $ref: "#/components/parameters/page" responses: 200: - description: List of organisations + description: List of organisations. content: application/json: schema: @@ -110,12 +113,12 @@ paths: default: $ref: "#/components/responses/UnexpectedError" post: - summary: Creates new organisation + summary: Creates a new organisation. operationId: createOrganisation tags: - organisation requestBody: - description: Organisation details + description: Organisation details. required: true content: application/json: @@ -123,7 +126,7 @@ paths: $ref: "#/components/schemas/Organisation" responses: 201: - description: Created organisation + description: Created organisation. content: application/json: schema: @@ -135,7 +138,7 @@ paths: /data_source: get: - summary: Returns a available and accessible data sources. + summary: Returns all available and accessible data sources. operationId: getDataSources tags: - data_source @@ -154,7 +157,7 @@ paths: $ref: "#/components/responses/UnexpectedError" /{organisationId}: - summary: Represents an organisation + summary: Represents an organisation. parameters: - name: organisationId in: path @@ -163,13 +166,13 @@ paths: type: string - $ref: "#/components/parameters/include" get: - summary: Returns a particular organisation + summary: Returns a particular organisation by ID. operationId: getOrganisationById tags: - organisation responses: 200: - description: Details of the organisation + description: Details of the organisation. content: application/json: schema: @@ -181,12 +184,12 @@ paths: default: $ref: "#/components/responses/UnexpectedError" patch: - summary: Updates a particular organisation by id and returns the result + summary: Updates a particular organisation by ID and returns the result. operationId: updateOrganisationById tags: - organisation requestBody: - description: Organisation details to be applied + description: Organisation details to be applied. required: true content: application/json: @@ -194,7 +197,7 @@ paths: $ref: "#/components/schemas/Organisation" responses: 200: - description: Details about the updated organisation + description: Details about the updated organisation. content: application/json: schema: @@ -206,7 +209,7 @@ paths: default: $ref: "#/components/responses/UnexpectedError" delete: - summary: Deletes a particular organisation by id and returns the deleted organisation + summary: Deletes a particular organisation by ID. operationId: deleteOrganisationById tags: - organisation @@ -224,7 +227,7 @@ paths: parameters: - $ref: "#/components/parameters/include" get: - summary: Searches for repositories. Use the query parameters to filter the result. + summary: Search for repositories. Use the query parameters to filter the result. operationId: getRepositories tags: - repository @@ -242,7 +245,7 @@ paths: - $ref: "#/components/parameters/page" responses: 200: - description: List of repositories + description: List of repositories. content: application/json: schema: @@ -258,7 +261,7 @@ paths: parameters: - $ref: "#/components/parameters/include" get: - summary: Searches for ontologies. Use the query parameters to filter the result. + summary: Search for ontologies. Use the query parameters to filter the result. operationId: getOntologies tags: - ontology @@ -271,7 +274,7 @@ paths: - $ref: "#/components/parameters/page" responses: 200: - description: List of ontologies + description: List of ontologies. content: application/json: schema: @@ -287,7 +290,9 @@ paths: parameters: - $ref: "#/components/parameters/include" get: - summary: Searches for phenotypes or categories. Use the query parameters to filter the result. Only entities in primary repositories are returned. + summary: > + Search for phenotypes or categories. Use the query parameters to filter the result. + Only entities in primary repositories are returned. operationId: getEntities tags: - entity @@ -305,14 +310,14 @@ paths: items: $ref: "#/components/schemas/EntityType" - name: dataType - description: Filter phenotypes or categories by data type + description: Filter phenotypes or categories by data type. in: query schema: $ref: "#/components/schemas/DataType" - $ref: "#/components/parameters/page" responses: 200: - description: List of phenotypes or categories + description: List of phenotypes or categories. content: application/json: schema: @@ -333,7 +338,7 @@ paths: type: string - $ref: "#/components/parameters/include" get: - summary: Searches for repositories in organisation. Use the query parameters to filter the result. + summary: Search for repositories in an organisation. Use the query parameters to filter the result. operationId: getRepositoriesByOrganisationId tags: - repository @@ -346,7 +351,7 @@ paths: - $ref: "#/components/parameters/page" responses: 200: - description: List of repositories + description: List of repositories. content: application/json: schema: @@ -360,12 +365,12 @@ paths: default: $ref: "#/components/responses/UnexpectedError" post: - summary: Creates new repository in organisation + summary: Creates new repository in organisation. operationId: createRepository tags: - repository requestBody: - description: Repository details + description: Repository details. required: true content: application/json: @@ -373,7 +378,7 @@ paths: $ref: "#/components/schemas/Repository" responses: 201: - description: Created repository + description: Created repository. content: application/json: schema: @@ -386,7 +391,7 @@ paths: $ref: "#/components/responses/UnexpectedError" /{organisationId}/{repositoryId}: - summary: Represents a repository in an organisation + summary: Represents a repository in an organisation. parameters: - name: organisationId in: path @@ -400,13 +405,13 @@ paths: type: string - $ref: "#/components/parameters/include" get: - summary: Returns a particular repository in organisation + summary: Returns a particular repository in an organisation. operationId: getRepositoryById tags: - repository responses: 200: - description: Details of the repository + description: Details of the repository. content: application/json: schema: @@ -418,12 +423,12 @@ paths: default: $ref: "#/components/responses/UnexpectedError" patch: - summary: Updates a particular repository by id in the organisation and returns the resulting repository + summary: Updates a particular repository by ID in the organisation and returns the resulting repository. operationId: updateRepositoryById tags: - repository requestBody: - description: Repository details to be applied + description: Repository details to be applied. required: true content: application/json: @@ -431,7 +436,7 @@ paths: $ref: "#/components/schemas/Repository" responses: 200: - description: Details about the updated repository + description: Details about the updated repository. content: application/json: schema: @@ -443,7 +448,7 @@ paths: default: $ref: "#/components/responses/UnexpectedError" delete: - summary: Deletes a particular repository by id in the organisation and returns the deleted repository + summary: Deletes a particular repository by ID in the organisation. operationId: deleteRepositoryById tags: - repository @@ -478,8 +483,7 @@ paths: - $ref: "#/components/parameters/page" responses: 200: - description: - List of queries. + description: List of queries. content: application/json: schema: @@ -495,7 +499,7 @@ paths: post: summary: > Enqueue a new query. You can get the query result with a GET request to the getQueryResult path. - The id property of the provided query object is used as identifier throughout the life-cycle of the query. + The ID property of the provided query object is used as identifier throughout the life-cycle of the query. operationId: enqueueQuery tags: - query @@ -539,7 +543,7 @@ paths: type: string format: uuid get: - summary: Returns the result of a particular query by id. + summary: Returns the result of a particular query by ID. operationId: getQueryResult tags: - query @@ -557,7 +561,7 @@ paths: default: $ref: "#/components/responses/UnexpectedError" delete: - summary: Deletes a particular query by id. + summary: Deletes a particular query by ID. operationId: deleteQuery tags: - query @@ -585,7 +589,7 @@ paths: type: string - $ref: "#/components/parameters/include" get: - summary: Searches for ontologies in repository. Use the query parameters to filter the result. + summary: Searches for ontologies in a repository. Use the query parameters to filter the result. operationId: getOntologiesByRepositoryId tags: - ontology @@ -598,7 +602,7 @@ paths: - $ref: "#/components/parameters/page" responses: 200: - description: List of ontologies + description: List of ontologies. content: application/json: schema: @@ -612,12 +616,12 @@ paths: default: $ref: "#/components/responses/UnexpectedError" post: - summary: Creates new ontology in repository + summary: Creates a new ontology in a repository. operationId: createOntology tags: - ontology requestBody: - description: Ontology details + description: Ontology details. required: true content: application/json: @@ -625,7 +629,7 @@ paths: $ref: "#/components/schemas/Ontology" responses: 201: - description: Created ontology + description: Created ontology. content: application/json: schema: @@ -638,7 +642,7 @@ paths: $ref: "#/components/responses/UnexpectedError" /{organisationId}/{repositoryId}/ontology/{ontologyId}/{version}: - summary: Represents an ontology in a repository + summary: Represents an ontology in a repository. parameters: - name: organisationId in: path @@ -662,13 +666,13 @@ paths: $ref: "#/components/schemas/VersionNumber" - $ref: "#/components/parameters/include" get: - summary: Returns a particular ontology in the repository + summary: Returns a particular ontology in a repository. operationId: getOntologyByName tags: - ontology responses: 200: - description: Details of the ontology + description: Details of the ontology. content: application/json: schema: @@ -680,12 +684,12 @@ paths: default: $ref: "#/components/responses/UnexpectedError" put: - summary: Updates a particular ontology by id in the repository and returns the result + summary: Updates a particular ontology by id in a repository and returns the result. operationId: updateOntologyById tags: - ontology requestBody: - description: Ontology details to be applied + description: Ontology details to be applied. required: true content: application/json: @@ -693,7 +697,7 @@ paths: $ref: "#/components/schemas/Ontology" responses: 200: - description: Details about the updated ontology + description: Details about the updated ontology. content: application/json: schema: @@ -705,13 +709,13 @@ paths: default: $ref: "#/components/responses/UnexpectedError" patch: - summary: Build a new release for the ontology + summary: Build a new release for the ontology. operationId: releaseOntology tags: - ontology responses: 200: - description: Details about the released ontology + description: Details about the released ontology. content: application/json: schema: @@ -723,7 +727,7 @@ paths: default: $ref: "#/components/schemas/ErrorResponse" delete: - summary: Deletes a particular ontology by id in the repository and returns the deleted ontology + summary: Deletes a particular ontology by ID in a repository. operationId: deleteOntologyById tags: - ontology @@ -751,7 +755,7 @@ paths: type: string - $ref: "#/components/parameters/include" get: - summary: Searches for phenotypes or categories. Use the query parameters to filter the result. + summary: Search for phenotypes or categories. Use the query parameters to filter the result. operationId: getEntitiesByRepositoryId tags: - entity @@ -769,14 +773,14 @@ paths: items: $ref: "#/components/schemas/EntityType" - name: dataType - description: Filter phenotypes or categories by data type + description: Filter phenotypes or categories by data type. in: query schema: $ref: "#/components/schemas/DataType" - $ref: "#/components/parameters/page" responses: 200: - description: List of phenotypes or categories + description: List of phenotypes or categories. content: application/json: schema: @@ -790,12 +794,12 @@ paths: default: $ref: "#/components/responses/UnexpectedError" post: - summary: Creates a new phenotype or category in the repository and returns the result + summary: Creates a new phenotype or category in a repository and returns the result. operationId: createEntity tags: - entity requestBody: - description: Phenotype or category details to be applied + description: Phenotype or category details to be applied. required: true content: application/json: @@ -803,7 +807,7 @@ paths: $ref: "#/components/schemas/Entity" responses: 200: - description: Details about the created phenotype or category + description: Details about the created phenotype or category. content: application/json: schema: @@ -829,7 +833,7 @@ paths: type: string - $ref: "#/components/parameters/include" get: - summary: Searches for root phenotypes or categories. Use the query parameters to filter the result. + summary: Search for root phenotypes or categories. Use the query parameters to filter the result. operationId: getRootEntitiesByRepositoryId tags: - entity @@ -847,14 +851,14 @@ paths: items: $ref: "#/components/schemas/EntityType" - name: dataType - description: Filter phenotypes or categories by data type + description: Filter phenotypes or categories by data type. in: query schema: $ref: "#/components/schemas/DataType" - $ref: "#/components/parameters/page" responses: 200: - description: List of root phenotypes or categories + description: List of root phenotypes or categories. content: application/json: schema: @@ -869,7 +873,7 @@ paths: $ref: "#/components/responses/UnexpectedError" /{organisationId}/{repositoryId}/{id}: - summary: Represents an entity (i.e. phenotype or category) in a repository + summary: Represents an entity (i.e. phenotype or category) in a repository. parameters: - name: organisationId in: path @@ -893,13 +897,13 @@ paths: $ref: "#/components/schemas/VersionNumber" - $ref: "#/components/parameters/include" get: - summary: Returns a particular phenotype or category in the repository + summary: Returns a particular phenotype or category in a repository. operationId: getEntityById tags: - entity responses: 200: - description: Details of the phenotype or category + description: Details of the phenotype or category. content: application/json: schema: @@ -911,12 +915,12 @@ paths: default: $ref: "#/components/responses/UnexpectedError" put: - summary: Updates a particular phenotype or category by id in the repository and returns the result + summary: Updates a particular phenotype or category by id in a repository and returns the result. operationId: updateEntityById tags: - entity requestBody: - description: Phenotype or category details to be applied + description: Phenotype or category details to be applied. required: true content: application/json: @@ -924,7 +928,7 @@ paths: $ref: "#/components/schemas/Entity" responses: 200: - description: Details about the updated phenotype or category + description: Details about the updated phenotype or category. content: application/json: schema: @@ -937,7 +941,7 @@ paths: $ref: "#/components/responses/UnexpectedError" delete: summary: - Deletes a particular phenotype or category by id in the repository. + Deletes a particular phenotype or category by ID in the repository. One can delete the whole entity or a version by specifying the version parameter. The current version of an entity cannot be deleted. operationId: deleteEntityById @@ -979,7 +983,7 @@ paths: $ref: "#/components/responses/UnexpectedError" /{organisationId}/{repositoryId}/{id}/export: - summary: Export entity in the requested format. + summary: Export an entity in the requested format. parameters: - name: organisationId in: path @@ -1076,7 +1080,7 @@ paths: schema: $ref: "#/components/schemas/VersionNumber" requestBody: - description: Forking instructions like destination + description: Forking instructions like destination. required: true content: application/json: @@ -1084,7 +1088,7 @@ paths: $ref: "#/components/schemas/ForkingInstruction" responses: 201: - description: List of affected entities (i.e., entities created in the destination repository). + description: List of affected entities (i.e., entities created or updated in the destination repository). content: application/json: schema: @@ -1099,7 +1103,7 @@ paths: $ref: "#/components/responses/UnexpectedError" /{organisationId}/{repositoryId}/{id}/history: - summary: Represents the version history of an entity (i.e. phenotype or category) in a repository + summary: Represents the version history of an entity (i.e. phenotype or category) in a repository. parameters: - name: organisationId in: path @@ -1118,13 +1122,13 @@ paths: type: string - $ref: "#/components/parameters/include" get: - summary: Returns all versions of a particular phenotype or category in the repository + summary: Returns all versions of a particular phenotype or category in a repository. operationId: getEntityVersionsById tags: - entity responses: 200: - description: List of versions + description: List of versions. content: application/json: schema: @@ -1139,7 +1143,7 @@ paths: $ref: "#/components/responses/UnexpectedError" /{organisationId}/{repositoryId}/{id}/subclasses: - summary: Represents subclasses (categories, abstract or restricted phenotypes) of an entity in a repository + summary: Represents subclasses (categories, abstract or restricted phenotypes) of an entity in a repository. parameters: - name: organisationId in: path @@ -1158,13 +1162,13 @@ paths: type: string - $ref: "#/components/parameters/include" get: - summary: Returns all subclasses of a particular phenotype or category in the repository + summary: Returns all subclasses of a particular phenotype or category in the repository. operationId: getSubclassesById tags: - entity responses: 200: - description: List of subclasses + description: List of subclasses. content: application/json: schema: @@ -1182,17 +1186,19 @@ paths: parameters: - name: type in: query - description: Optional parameter to restrict the result set to a specific function type (to be defined). + description: > + Optional parameter to restrict the result set to a specific function type. + Currently, 'math' and 'boolean' are supported. schema: type: string get: - summary: Get all supported expression functions + summary: Get all supported expression functions. operationId: getExpressionFunctions tags: - expression_function responses: 200: - description: List of supported expression functions + description: List of supported expression functions. content: application/json: schema: @@ -1206,13 +1212,13 @@ paths: /expression_constant: get: - summary: Get all supported expression constants + summary: Get all supported expression constants. operationId: getExpressionConstants tags: - expression_constant responses: 200: - description: List of supported expression constants + description: List of supported expression constants. content: application/json: schema: @@ -1227,21 +1233,21 @@ paths: components: responses: NotFound: - description: The specified resource was not found + description: The specified resource was not found. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" Unauthorized: - description: Unauthorized, Access token is missing or invalid + description: Unauthorized, Access token is missing or invalid. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" UnexpectedError: - description: Unexpected error + description: Unexpected error. content: application/json: schema: @@ -1281,7 +1287,7 @@ components: description: type: string primary: - description: Determines whether this repository is a primary (aka. public) repository + description: Determines whether this repository is a primary (aka. public) repository. type: boolean default: false createdAt: @@ -1332,7 +1338,7 @@ components: $ref: "#/components/schemas/Organisation" Entity: - description: Either category or phenotype + description: Either category or phenotype. type: object required: - entityType @@ -1343,7 +1349,7 @@ components: type: string titles: type: array - description: There should only be one title per language + description: There should only be one title per language. items: $ref: "#/components/schemas/LocalisableText" synonyms: @@ -1359,6 +1365,7 @@ components: format: int32 minimum: 1 codes: + description: E.g. LOINC or ICD-10 codes. type: array items: $ref: "#/components/schemas/Code" @@ -1509,13 +1516,13 @@ components: values: type: array description: > - This property is for internal use only and will be ignored, if sent to a backend. + This property is for internal use only and will be ignored, if sent to a server. Items of this array property can hold results of function calls contained in expressions. items: $ref: "#/components/schemas/Value" restriction: description: > - This property is for internal use only and will be ignored, if sent to a backend. + This property is for internal use only and will be ignored, if sent to a server. Restrictions can be stored in this property to simplify the construction of phenotypic queries. $ref: "#/components/schemas/Restriction" @@ -1527,7 +1534,7 @@ components: $ref: "#/components/schemas/DataType" dateTime: description: > - This property is for internal use only and will be ignored, if sent to a backend. + This property is for internal use only and will be ignored, if sent to a server. This property specifies when a value has been observed. type: string format: x-local-date-time @@ -1673,18 +1680,18 @@ components: format: uri LocalisableText: - description: A text in a specific language + description: A text in a specific language. type: object required: - lang - text properties: lang: - description: ICU Locale code + description: ICU Locale code. type: string pattern: '^[a-z]{2}(-[A-Z\-]+)?$' text: - description: The actual localised text + description: The actual localised text. type: string CodeSystem: @@ -1700,7 +1707,7 @@ components: type: string Code: - description: Code of a code system + description: Code of a code system. type: object required: - codeSystem @@ -1714,7 +1721,7 @@ components: type: string Restriction: - description: Represents restriction of an abstract phenotype + description: Represents restriction of an abstract phenotype. type: object required: - type @@ -1724,7 +1731,9 @@ components: quantifier: $ref: "#/components/schemas/Quantifier" cardinality: - description: This value can be used in combination with a quantifier to specify how many matches are required to fulfil this restriction. + description: > + This value can be used in combination with a quantifier to specify + how many matches are required to fulfil this restriction. type: integer format: int32 minimum: 0 @@ -1765,7 +1774,11 @@ components: $ref: "#/components/schemas/RestrictionOperator" values: type: array - description: In case there are operators, the first two values are used as values for those operators + description: > + In case there are operators, the first two values are used as values for these operators. + Convention: + The first array item will always be treated as minimum and the second one as maximum. + In case there is only a maximum value, the first array item is null. items: type: number allOf: @@ -1780,7 +1793,11 @@ components: $ref: "#/components/schemas/RestrictionOperator" values: type: array - description: In case there are operators, the first two values are used as values for those operators + description: > + In case there are operators, the first two values are used as values for these operators. + Convention: + The first array item will always be treated as minimum and the second one as maximum. + In case there is only a maximum value, the first array item is null. items: type: string format: x-local-date-time @@ -1811,7 +1828,9 @@ components: type: string format: uuid name: - description: Name of this query. For example, you could allow users to save a query for later use and use the name as identifier. + description: > + Name of this query. For example, you could allow users to save a query + for later use and use the name as identifier. type: string dataSources: type: array @@ -1908,8 +1927,10 @@ components: defaultAggregationFunctionId: type: string description: > - Multiple phenotype values in expressions must be aggregated to a single value in order to use them for calculations. - The aggregation function provided via this property will be used as default aggregation function for cases where none has been set. + Multiple phenotype values in expressions must be aggregated to + a single value in order to use them for calculations. + The aggregation function provided via this property will be used as + default aggregation function for cases where none has been set. dateTimeRestriction: $ref: "#/components/schemas/DateTimeRestriction" @@ -1953,19 +1974,19 @@ components: type: object properties: organisations: - description: Number of organisations + description: Number of organisations. type: integer format: int64 repositories: - description: Number of repositories + description: Number of repositories. type: integer format: int64 categories: - description: Number of phenotype categories + description: Number of phenotype categories. type: integer format: int64 phenotypes: - description: Number of phenotypes + description: Number of phenotypes. type: integer format: int64 From eca3a9ef078ba9613c430ca8c8b48f686cc5ff8c Mon Sep 17 00:00:00 2001 From: Christoph Beger Date: Thu, 13 Oct 2022 10:15:28 +0200 Subject: [PATCH 02/12] Reformat schema --- README.md | 8 + schemas/top-api.yml | 1494 ++++++++++++++++++++----------------------- 2 files changed, 705 insertions(+), 797 deletions(-) diff --git a/README.md b/README.md index 16969a6..7cee69b 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,14 @@ The container has the [OpenAPI (Swagger) Editor](https://marketplace.visualstudi Create new releases via GitHub Workflow [publish-snapshots.yml](.github/workflows/publish-snapshots.yml). Doing so will automaticaly build and publish a new Spring Boot skeleton package, generated with [https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator-maven-plugin](openapi-generator-maven-plugin). Please update the version number in the [pom.xml](pom.xml) and [schemas/top-api.yml](schemas/top-api.yml) files **after** publishing a release. +### Format Schema File + +You can use the npm package [openapi-format](https://www.npmjs.com/package/openapi-format) to automatically format the OpenApi schema file. + +``` +npx openapi-format schemas/top-api.yml --output schemas/top-api.yml +``` + ### Versioning There will always be a snapshot version available with latest changes pushed to the main branch. Snapshots have a higher version number than the last release. diff --git a/schemas/top-api.yml b/schemas/top-api.yml index 1769e3e..7e0708a 100644 --- a/schemas/top-api.yml +++ b/schemas/top-api.yml @@ -2,68 +2,61 @@ openapi: 3.0.0 info: title: TOP API version: 0.5.1 - description: API to manage phenotypes, repositories, ontologies and organisations and to execute phenotypic queries. - + description: 'API to manage phenotypes, repositories, ontologies and organisations and to execute phenotypic queries.' servers: - - url: https://top.imise.uni-leipzig.de/api + - url: 'https://top.imise.uni-leipzig.de/api' description: Public demo server. - - url: http://localhost:8080 + - url: 'http://localhost:8080' description: Local development instance. - - url: http://host.docker.internal:8080 + - url: 'http://host.docker.internal:8080' description: In case the server is running on the Docker host. - paths: /metadata: get: - summary: Get OpenAPI description of this API. operationId: getMetadata - security: - - BearerAuth: [] - - BasicAuth: [] + summary: Get OpenAPI description of this API. responses: - 200: + '200': description: API metadata content: text/plain: schema: type: string - - /ping: - get: - summary: Checks if the server is running. - operationId: ping security: - BearerAuth: [] - BasicAuth: [] + /ping: + get: + operationId: ping + summary: Checks if the server is running. responses: - 200: + '200': description: Server is up and running. default: - $ref: "#/components/responses/UnexpectedError" - + $ref: '#/components/responses/UnexpectedError' + security: + - BearerAuth: [] + - BasicAuth: [] /statistic: summary: Get statistics about available content. Returned data may be cached. get: operationId: getStatistics - security: - - BearerAuth: [] - - BasicAuth: [] responses: - 200: + '200': description: Object holding statistics. content: application/json: schema: - $ref: "#/components/schemas/Statistic" + $ref: '#/components/schemas/Statistic' default: - $ref: "#/components/responses/UnexpectedError" - + $ref: '#/components/responses/UnexpectedError' + security: + - BearerAuth: [] + - BasicAuth: [] /document: get: - summary: Searches for documents. operationId: getDocuments - tags: - - document + summary: Searches for documents. parameters: - name: id in: query @@ -71,92 +64,91 @@ paths: schema: type: string responses: - 200: + '200': description: List of documents. content: application/json: schema: type: array items: - $ref: "#/components/schemas/Document" - 401: - $ref: "#/components/responses/Unauthorized" + $ref: '#/components/schemas/Document' + '401': + $ref: '#/components/responses/Unauthorized' default: - $ref: "#/components/responses/UnexpectedError" - + $ref: '#/components/responses/UnexpectedError' + tags: + - document /organisation: parameters: - - $ref: "#/components/parameters/include" + - $ref: '#/components/parameters/include' get: - summary: Search for organisations. Use the query parameters to filter the result. operationId: getOrganisations - tags: - - organisation + summary: Search for organisations. Use the query parameters to filter the result. parameters: - name: name - description: Filter organisations by name. in: query + description: Filter organisations by name. schema: type: string - - $ref: "#/components/parameters/page" + - $ref: '#/components/parameters/page' responses: - 200: + '200': description: List of organisations. content: application/json: schema: type: array items: - $ref: "#/components/schemas/Organisation" - 401: - $ref: "#/components/responses/Unauthorized" + $ref: '#/components/schemas/Organisation' + '401': + $ref: '#/components/responses/Unauthorized' default: - $ref: "#/components/responses/UnexpectedError" - post: - summary: Creates a new organisation. - operationId: createOrganisation + $ref: '#/components/responses/UnexpectedError' tags: - organisation + post: + operationId: createOrganisation + summary: Creates a new organisation. requestBody: description: Organisation details. - required: true content: application/json: schema: - $ref: "#/components/schemas/Organisation" + $ref: '#/components/schemas/Organisation' + required: true responses: - 201: + '201': description: Created organisation. content: application/json: schema: - $ref: "#/components/schemas/Organisation" - 401: - $ref: "#/components/responses/Unauthorized" + $ref: '#/components/schemas/Organisation' + '401': + $ref: '#/components/responses/Unauthorized' default: - $ref: "#/components/responses/UnexpectedError" - + $ref: '#/components/responses/UnexpectedError' + tags: + - organisation /data_source: get: - summary: Returns all available and accessible data sources. operationId: getDataSources - tags: - - data_source + summary: Returns all available and accessible data sources. responses: - 200: + '200': description: List of data sources. content: application/json: schema: type: array items: - $ref: "#/components/schemas/DataSource" - 401: - $ref: "#/components/responses/Unauthorized" + $ref: '#/components/schemas/DataSource' + '401': + $ref: '#/components/responses/Unauthorized' default: - $ref: "#/components/responses/UnexpectedError" - - /{organisationId}: + $ref: '#/components/responses/UnexpectedError' + tags: + - data_source + '/{organisationId}': summary: Represents an organisation. parameters: - name: organisationId @@ -164,233 +156,227 @@ paths: required: true schema: type: string - - $ref: "#/components/parameters/include" + - $ref: '#/components/parameters/include' get: - summary: Returns a particular organisation by ID. operationId: getOrganisationById - tags: - - organisation + summary: Returns a particular organisation by ID. responses: - 200: + '200': description: Details of the organisation. content: application/json: schema: - $ref: "#/components/schemas/Organisation" - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + $ref: '#/components/schemas/Organisation' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' default: - $ref: "#/components/responses/UnexpectedError" - patch: - summary: Updates a particular organisation by ID and returns the result. - operationId: updateOrganisationById + $ref: '#/components/responses/UnexpectedError' tags: - organisation + patch: + operationId: updateOrganisationById + summary: Updates a particular organisation by ID and returns the result. requestBody: description: Organisation details to be applied. - required: true content: application/json: schema: - $ref: "#/components/schemas/Organisation" + $ref: '#/components/schemas/Organisation' + required: true responses: - 200: + '200': description: Details about the updated organisation. content: application/json: schema: - $ref: "#/components/schemas/Organisation" - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + $ref: '#/components/schemas/Organisation' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' default: - $ref: "#/components/responses/UnexpectedError" - delete: - summary: Deletes a particular organisation by ID. - operationId: deleteOrganisationById + $ref: '#/components/responses/UnexpectedError' tags: - organisation + delete: + operationId: deleteOrganisationById + summary: Deletes a particular organisation by ID. responses: - 204: + '204': description: The organisation was deleted successfully. - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' default: - $ref: "#/components/responses/UnexpectedError" - + $ref: '#/components/responses/UnexpectedError' + tags: + - organisation /repository: parameters: - - $ref: "#/components/parameters/include" + - $ref: '#/components/parameters/include' get: - summary: Search for repositories. Use the query parameters to filter the result. operationId: getRepositories - tags: - - repository + summary: Search for repositories. Use the query parameters to filter the result. parameters: - name: name - description: Filter repositories by name. in: query + description: Filter repositories by name. schema: type: string - name: primary - description: Filter repositories by primary state. in: query + description: Filter repositories by primary state. schema: type: boolean - - $ref: "#/components/parameters/page" + - $ref: '#/components/parameters/page' responses: - 200: + '200': description: List of repositories. content: application/json: schema: type: array items: - $ref: "#/components/schemas/Repository" - 401: - $ref: "#/components/responses/Unauthorized" + $ref: '#/components/schemas/Repository' + '401': + $ref: '#/components/responses/Unauthorized' default: - $ref: "#/components/responses/UnexpectedError" - + $ref: '#/components/responses/UnexpectedError' + tags: + - repository /ontology: parameters: - - $ref: "#/components/parameters/include" + - $ref: '#/components/parameters/include' get: - summary: Search for ontologies. Use the query parameters to filter the result. operationId: getOntologies - tags: - - ontology + summary: Search for ontologies. Use the query parameters to filter the result. parameters: - name: name - description: Filter ontologies by name. in: query + description: Filter ontologies by name. schema: type: string - - $ref: "#/components/parameters/page" + - $ref: '#/components/parameters/page' responses: - 200: + '200': description: List of ontologies. content: application/json: schema: type: array items: - $ref: "#/components/schemas/Ontology" - 401: - $ref: "#/components/responses/Unauthorized" + $ref: '#/components/schemas/Ontology' + '401': + $ref: '#/components/responses/Unauthorized' default: - $ref: "#/components/responses/UnexpectedError" - + $ref: '#/components/responses/UnexpectedError' + tags: + - ontology /entity: parameters: - - $ref: "#/components/parameters/include" + - $ref: '#/components/parameters/include' get: - summary: > - Search for phenotypes or categories. Use the query parameters to filter the result. - Only entities in primary repositories are returned. operationId: getEntities - tags: - - entity + summary: | + Search for phenotypes or categories. Use the query parameters to filter the result. Only entities in primary repositories are returned. parameters: - name: name - description: Filter phenotypes or categories by name. in: query + description: Filter phenotypes or categories by name. schema: type: string - name: type - description: Filter phenotypes or categories by type. in: query + description: Filter phenotypes or categories by type. schema: type: array items: - $ref: "#/components/schemas/EntityType" + $ref: '#/components/schemas/EntityType' - name: dataType - description: Filter phenotypes or categories by data type. in: query + description: Filter phenotypes or categories by data type. schema: - $ref: "#/components/schemas/DataType" - - $ref: "#/components/parameters/page" + $ref: '#/components/schemas/DataType' + - $ref: '#/components/parameters/page' responses: - 200: + '200': description: List of phenotypes or categories. content: application/json: schema: type: array items: - $ref: "#/components/schemas/Entity" - 401: - $ref: "#/components/responses/Unauthorized" + $ref: '#/components/schemas/Entity' + '401': + $ref: '#/components/responses/Unauthorized' default: - $ref: "#/components/responses/UnexpectedError" - - /{organisationId}/repository: + $ref: '#/components/responses/UnexpectedError' + tags: + - entity + '/{organisationId}/repository': parameters: - name: organisationId in: path required: true schema: type: string - - $ref: "#/components/parameters/include" + - $ref: '#/components/parameters/include' get: - summary: Search for repositories in an organisation. Use the query parameters to filter the result. operationId: getRepositoriesByOrganisationId - tags: - - repository + summary: Search for repositories in an organisation. Use the query parameters to filter the result. parameters: - name: name - description: Filter repositories by name. in: query + description: Filter repositories by name. schema: type: string - - $ref: "#/components/parameters/page" + - $ref: '#/components/parameters/page' responses: - 200: + '200': description: List of repositories. content: application/json: schema: type: array items: - $ref: "#/components/schemas/Repository" - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + $ref: '#/components/schemas/Repository' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' default: - $ref: "#/components/responses/UnexpectedError" - post: - summary: Creates new repository in organisation. - operationId: createRepository + $ref: '#/components/responses/UnexpectedError' tags: - repository + post: + operationId: createRepository + summary: Creates new repository in organisation. requestBody: description: Repository details. - required: true content: application/json: schema: - $ref: "#/components/schemas/Repository" + $ref: '#/components/schemas/Repository' + required: true responses: - 201: + '201': description: Created repository. content: application/json: schema: - $ref: "#/components/schemas/Repository" - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + $ref: '#/components/schemas/Repository' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' default: - $ref: "#/components/responses/UnexpectedError" - - /{organisationId}/{repositoryId}: + $ref: '#/components/responses/UnexpectedError' + tags: + - repository + '/{organisationId}/{repositoryId}': summary: Represents a repository in an organisation. parameters: - name: organisationId @@ -403,66 +389,65 @@ paths: required: true schema: type: string - - $ref: "#/components/parameters/include" + - $ref: '#/components/parameters/include' get: - summary: Returns a particular repository in an organisation. operationId: getRepositoryById - tags: - - repository + summary: Returns a particular repository in an organisation. responses: - 200: + '200': description: Details of the repository. content: application/json: schema: - $ref: "#/components/schemas/Repository" - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + $ref: '#/components/schemas/Repository' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' default: - $ref: "#/components/responses/UnexpectedError" - patch: - summary: Updates a particular repository by ID in the organisation and returns the resulting repository. - operationId: updateRepositoryById + $ref: '#/components/responses/UnexpectedError' tags: - repository + patch: + operationId: updateRepositoryById + summary: Updates a particular repository by ID in the organisation and returns the resulting repository. requestBody: description: Repository details to be applied. - required: true content: application/json: schema: - $ref: "#/components/schemas/Repository" + $ref: '#/components/schemas/Repository' + required: true responses: - 200: + '200': description: Details about the updated repository. content: application/json: schema: - $ref: "#/components/schemas/Repository" - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + $ref: '#/components/schemas/Repository' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' default: - $ref: "#/components/responses/UnexpectedError" - delete: - summary: Deletes a particular repository by ID in the organisation. - operationId: deleteRepositoryById + $ref: '#/components/responses/UnexpectedError' tags: - repository + delete: + operationId: deleteRepositoryById + summary: Deletes a particular repository by ID in the organisation. responses: - 204: + '204': description: The repository was deleted successfully. - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' default: - $ref: "#/components/responses/UnexpectedError" - - /{organisationId}/{repositoryId}/query: + $ref: '#/components/responses/UnexpectedError' + tags: + - repository + '/{organisationId}/{repositoryId}/query': parameters: - name: organisationId in: path @@ -475,56 +460,54 @@ paths: schema: type: string get: - summary: Returns a list of all queries for the specified repository. operationId: getQueries - tags: - - query + summary: Returns a list of all queries for the specified repository. parameters: - - $ref: "#/components/parameters/page" + - $ref: '#/components/parameters/page' responses: - 200: + '200': description: List of queries. content: application/json: schema: type: array items: - $ref: "#/components/schemas/Query" - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + $ref: '#/components/schemas/Query' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' default: - $ref: "#/components/responses/UnexpectedError" - post: - summary: > - Enqueue a new query. You can get the query result with a GET request to the getQueryResult path. - The ID property of the provided query object is used as identifier throughout the life-cycle of the query. - operationId: enqueueQuery + $ref: '#/components/responses/UnexpectedError' tags: - query + post: + operationId: enqueueQuery + summary: | + Enqueue a new query. You can get the query result with a GET request to the getQueryResult path. The ID property of the provided query object is used as identifier throughout the life-cycle of the query. requestBody: description: Details of the query to be enqueued. - required: true content: application/json: schema: - $ref: "#/components/schemas/Query" + $ref: '#/components/schemas/Query' + required: true responses: - 201: + '201': description: The query was enqueued successfully. content: application/json: schema: - $ref: "#/components/schemas/QueryResult" - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + $ref: '#/components/schemas/QueryResult' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' default: - $ref: "#/components/responses/UnexpectedError" - - /{organisationId}/{repositoryId}/query/{queryId}: + $ref: '#/components/responses/UnexpectedError' + tags: + - query + '/{organisationId}/{repositoryId}/query/{queryId}': parameters: - name: organisationId in: path @@ -543,39 +526,38 @@ paths: type: string format: uuid get: - summary: Returns the result of a particular query by ID. operationId: getQueryResult - tags: - - query + summary: Returns the result of a particular query by ID. responses: - 200: + '200': description: Details of the query result. content: application/json: schema: - $ref: "#/components/schemas/QueryResult" - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + $ref: '#/components/schemas/QueryResult' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' default: - $ref: "#/components/responses/UnexpectedError" - delete: - summary: Deletes a particular query by ID. - operationId: deleteQuery + $ref: '#/components/responses/UnexpectedError' tags: - query + delete: + operationId: deleteQuery + summary: Deletes a particular query by ID. responses: - 204: + '204': description: The query was deleted successfully. - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' default: - $ref: "#/components/responses/UnexpectedError" - - /{organisationId}/{repositoryId}/ontology: + $ref: '#/components/responses/UnexpectedError' + tags: + - query + '/{organisationId}/{repositoryId}/ontology': parameters: - name: organisationId in: path @@ -587,61 +569,60 @@ paths: required: true schema: type: string - - $ref: "#/components/parameters/include" + - $ref: '#/components/parameters/include' get: - summary: Searches for ontologies in a repository. Use the query parameters to filter the result. operationId: getOntologiesByRepositoryId - tags: - - ontology + summary: Searches for ontologies in a repository. Use the query parameters to filter the result. parameters: - name: name - description: Filter ontologies by name. in: query + description: Filter ontologies by name. schema: type: string - - $ref: "#/components/parameters/page" + - $ref: '#/components/parameters/page' responses: - 200: + '200': description: List of ontologies. content: application/json: schema: type: array items: - $ref: "#/components/schemas/Ontology" - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + $ref: '#/components/schemas/Ontology' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' default: - $ref: "#/components/responses/UnexpectedError" - post: - summary: Creates a new ontology in a repository. - operationId: createOntology + $ref: '#/components/responses/UnexpectedError' tags: - ontology + post: + operationId: createOntology + summary: Creates a new ontology in a repository. requestBody: description: Ontology details. - required: true content: application/json: schema: - $ref: "#/components/schemas/Ontology" + $ref: '#/components/schemas/Ontology' + required: true responses: - 201: + '201': description: Created ontology. content: application/json: schema: - $ref: "#/components/schemas/Ontology" - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + $ref: '#/components/schemas/Ontology' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' default: - $ref: "#/components/responses/UnexpectedError" - - /{organisationId}/{repositoryId}/ontology/{ontologyId}/{version}: + $ref: '#/components/responses/UnexpectedError' + tags: + - ontology + '/{organisationId}/{repositoryId}/ontology/{ontologyId}/{version}': summary: Represents an ontology in a repository. parameters: - name: organisationId @@ -663,85 +644,84 @@ paths: in: path required: true schema: - $ref: "#/components/schemas/VersionNumber" - - $ref: "#/components/parameters/include" + $ref: '#/components/schemas/VersionNumber' + - $ref: '#/components/parameters/include' get: - summary: Returns a particular ontology in a repository. operationId: getOntologyByName - tags: - - ontology + summary: Returns a particular ontology in a repository. responses: - 200: + '200': description: Details of the ontology. content: application/json: schema: - $ref: "#/components/schemas/Ontology" - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + $ref: '#/components/schemas/Ontology' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' default: - $ref: "#/components/responses/UnexpectedError" - put: - summary: Updates a particular ontology by id in a repository and returns the result. - operationId: updateOntologyById + $ref: '#/components/responses/UnexpectedError' tags: - ontology + put: + operationId: updateOntologyById + summary: Updates a particular ontology by id in a repository and returns the result. requestBody: description: Ontology details to be applied. - required: true content: application/json: schema: - $ref: "#/components/schemas/Ontology" + $ref: '#/components/schemas/Ontology' + required: true responses: - 200: + '200': description: Details about the updated ontology. content: application/json: schema: - $ref: "#/components/schemas/Ontology" - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + $ref: '#/components/schemas/Ontology' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' default: - $ref: "#/components/responses/UnexpectedError" - patch: - summary: Build a new release for the ontology. - operationId: releaseOntology + $ref: '#/components/responses/UnexpectedError' tags: - ontology + patch: + operationId: releaseOntology + summary: Build a new release for the ontology. responses: - 200: + '200': description: Details about the released ontology. content: application/json: schema: - $ref: "#/components/schemas/Ontology" - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + $ref: '#/components/schemas/Ontology' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' default: - $ref: "#/components/schemas/ErrorResponse" - delete: - summary: Deletes a particular ontology by ID in a repository. - operationId: deleteOntologyById + $ref: '#/components/schemas/ErrorResponse' tags: - ontology + delete: + operationId: deleteOntologyById + summary: Deletes a particular ontology by ID in a repository. responses: - 204: + '204': description: The ontology was deleted successfully. - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' default: - $ref: "#/components/responses/UnexpectedError" - - /{organisationId}/{repositoryId}/entity: + $ref: '#/components/responses/UnexpectedError' + tags: + - ontology + '/{organisationId}/{repositoryId}/entity': parameters: - name: organisationId in: path @@ -753,73 +733,72 @@ paths: required: true schema: type: string - - $ref: "#/components/parameters/include" + - $ref: '#/components/parameters/include' get: - summary: Search for phenotypes or categories. Use the query parameters to filter the result. operationId: getEntitiesByRepositoryId - tags: - - entity + summary: Search for phenotypes or categories. Use the query parameters to filter the result. parameters: - name: name - description: Filter phenotypes or categories by name. in: query + description: Filter phenotypes or categories by name. schema: type: string - name: type - description: Filter phenotypes or categories by type. in: query + description: Filter phenotypes or categories by type. schema: type: array items: - $ref: "#/components/schemas/EntityType" + $ref: '#/components/schemas/EntityType' - name: dataType - description: Filter phenotypes or categories by data type. in: query + description: Filter phenotypes or categories by data type. schema: - $ref: "#/components/schemas/DataType" - - $ref: "#/components/parameters/page" + $ref: '#/components/schemas/DataType' + - $ref: '#/components/parameters/page' responses: - 200: + '200': description: List of phenotypes or categories. content: application/json: schema: type: array items: - $ref: "#/components/schemas/Entity" - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + $ref: '#/components/schemas/Entity' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' default: - $ref: "#/components/responses/UnexpectedError" - post: - summary: Creates a new phenotype or category in a repository and returns the result. - operationId: createEntity + $ref: '#/components/responses/UnexpectedError' tags: - entity + post: + operationId: createEntity + summary: Creates a new phenotype or category in a repository and returns the result. requestBody: description: Phenotype or category details to be applied. - required: true content: application/json: schema: - $ref: "#/components/schemas/Entity" + $ref: '#/components/schemas/Entity' + required: true responses: - 200: + '200': description: Details about the created phenotype or category. content: application/json: schema: - $ref: "#/components/schemas/Entity" - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + $ref: '#/components/schemas/Entity' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' default: - $ref: "#/components/responses/UnexpectedError" - - /{organisationId}/{repositoryId}/root: + $ref: '#/components/responses/UnexpectedError' + tags: + - entity + '/{organisationId}/{repositoryId}/root': parameters: - name: organisationId in: path @@ -831,48 +810,47 @@ paths: required: true schema: type: string - - $ref: "#/components/parameters/include" + - $ref: '#/components/parameters/include' get: - summary: Search for root phenotypes or categories. Use the query parameters to filter the result. operationId: getRootEntitiesByRepositoryId - tags: - - entity + summary: Search for root phenotypes or categories. Use the query parameters to filter the result. parameters: - name: name - description: Filter phenotypes or categories by name. in: query + description: Filter phenotypes or categories by name. schema: type: string - name: type - description: Filter phenotypes or categories by type. in: query + description: Filter phenotypes or categories by type. schema: type: array items: - $ref: "#/components/schemas/EntityType" + $ref: '#/components/schemas/EntityType' - name: dataType - description: Filter phenotypes or categories by data type. in: query + description: Filter phenotypes or categories by data type. schema: - $ref: "#/components/schemas/DataType" - - $ref: "#/components/parameters/page" + $ref: '#/components/schemas/DataType' + - $ref: '#/components/parameters/page' responses: - 200: + '200': description: List of root phenotypes or categories. content: application/json: schema: type: array items: - $ref: "#/components/schemas/Entity" - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + $ref: '#/components/schemas/Entity' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' default: - $ref: "#/components/responses/UnexpectedError" - - /{organisationId}/{repositoryId}/{id}: + $ref: '#/components/responses/UnexpectedError' + tags: + - entity + '/{organisationId}/{repositoryId}/{id}': summary: Represents an entity (i.e. phenotype or category) in a repository. parameters: - name: organisationId @@ -891,98 +869,94 @@ paths: schema: type: string - name: version - description: Defaults to the latest version number. in: query + description: Defaults to the latest version number. schema: - $ref: "#/components/schemas/VersionNumber" - - $ref: "#/components/parameters/include" + $ref: '#/components/schemas/VersionNumber' + - $ref: '#/components/parameters/include' get: - summary: Returns a particular phenotype or category in a repository. operationId: getEntityById - tags: - - entity + summary: Returns a particular phenotype or category in a repository. responses: - 200: + '200': description: Details of the phenotype or category. content: application/json: schema: - $ref: "#/components/schemas/Entity" - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + $ref: '#/components/schemas/Entity' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' default: - $ref: "#/components/responses/UnexpectedError" - put: - summary: Updates a particular phenotype or category by id in a repository and returns the result. - operationId: updateEntityById + $ref: '#/components/responses/UnexpectedError' tags: - entity + put: + operationId: updateEntityById + summary: Updates a particular phenotype or category by id in a repository and returns the result. requestBody: description: Phenotype or category details to be applied. - required: true content: application/json: schema: - $ref: "#/components/schemas/Entity" + $ref: '#/components/schemas/Entity' + required: true responses: - 200: + '200': description: Details about the updated phenotype or category. content: application/json: schema: - $ref: "#/components/schemas/Entity" - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + $ref: '#/components/schemas/Entity' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' default: - $ref: "#/components/responses/UnexpectedError" - delete: - summary: - Deletes a particular phenotype or category by ID in the repository. - One can delete the whole entity or a version by specifying the version parameter. - The current version of an entity cannot be deleted. - operationId: deleteEntityById + $ref: '#/components/responses/UnexpectedError' tags: - entity + delete: + operationId: deleteEntityById + summary: Deletes a particular phenotype or category by ID in the repository. One can delete the whole entity or a version by specifying the version parameter. The current version of an entity cannot be deleted. responses: - 204: + '204': description: The entity or version was deleted successfully. - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' default: - $ref: "#/components/responses/UnexpectedError" - patch: - summary: Reset the state of a particular phenotype or category to the specified version. - operationId: setCurrentEntityVersion + $ref: '#/components/responses/UnexpectedError' tags: - entity + patch: + operationId: setCurrentEntityVersion + summary: Reset the state of a particular phenotype or category to the specified version. parameters: - name: version - description: Defaults to the latest version number. in: query + description: Defaults to the latest version number. required: true schema: - $ref: "#/components/schemas/VersionNumber" + $ref: '#/components/schemas/VersionNumber' responses: - 200: + '200': description: The current version of the entity after performing the reset. content: application/json: schema: - $ref: "#/components/schemas/Entity" - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + $ref: '#/components/schemas/Entity' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' default: - $ref: "#/components/responses/UnexpectedError" - - /{organisationId}/{repositoryId}/{id}/export: + $ref: '#/components/responses/UnexpectedError' + tags: + - entity + '/{organisationId}/{repositoryId}/{id}/export': summary: Export an entity in the requested format. parameters: - name: organisationId @@ -1001,36 +975,35 @@ paths: schema: type: string - name: version - description: Defaults to the latest version number. in: query + description: Defaults to the latest version number. schema: - $ref: "#/components/schemas/VersionNumber" + $ref: '#/components/schemas/VersionNumber' - name: format - description: The export format. in: query + description: The export format. required: true schema: type: string get: operationId: exportEntity - tags: - - entity responses: - 200: + '200': description: The entity in the requested export format. content: text/plain: schema: type: string - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' default: - $ref: "#/components/responses/UnexpectedError" - - /{organisationId}/{repositoryId}/{id}/fork: - summary: Manage forks of an entity. E.g. create new forks, list them and apply updates from origin. + $ref: '#/components/responses/UnexpectedError' + tags: + - entity + '/{organisationId}/{repositoryId}/{id}/fork': + summary: 'Manage forks of an entity. E.g. create new forks, list them and apply updates from origin.' parameters: - name: organisationId in: path @@ -1047,62 +1020,60 @@ paths: required: true schema: type: string - - $ref: "#/components/parameters/include" + - $ref: '#/components/parameters/include' get: - summary: Returns all forks of a particular entity and the originating class of the entity, if present. operationId: getForks - tags: - - fork + summary: 'Returns all forks of a particular entity and the originating class of the entity, if present.' responses: - 200: + '200': description: Forking stats that contain a list of forked entities and the originating entity. content: application/json: schema: - $ref: "#/components/schemas/ForkingStats" - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + $ref: '#/components/schemas/ForkingStats' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' default: - $ref: "#/components/responses/UnexpectedError" - post: - summary: > - Create a new fork from a particular entity. - Updates to existing forks can be applied via forking instructions. - operationId: createFork + $ref: '#/components/responses/UnexpectedError' tags: - fork + post: + operationId: createFork + summary: | + Create a new fork from a particular entity. Updates to existing forks can be applied via forking instructions. parameters: - name: version - description: Defaults to the latest version number. in: query + description: Defaults to the latest version number. schema: - $ref: "#/components/schemas/VersionNumber" + $ref: '#/components/schemas/VersionNumber' requestBody: description: Forking instructions like destination. - required: true content: application/json: schema: - $ref: "#/components/schemas/ForkingInstruction" + $ref: '#/components/schemas/ForkingInstruction' + required: true responses: - 201: - description: List of affected entities (i.e., entities created or updated in the destination repository). + '201': + description: 'List of affected entities (i.e., entities created or updated in the destination repository).' content: application/json: schema: type: array items: - $ref: "#/components/schemas/Entity" - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + $ref: '#/components/schemas/Entity' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' default: - $ref: "#/components/responses/UnexpectedError" - - /{organisationId}/{repositoryId}/{id}/history: + $ref: '#/components/responses/UnexpectedError' + tags: + - fork + '/{organisationId}/{repositoryId}/{id}/history': summary: Represents the version history of an entity (i.e. phenotype or category) in a repository. parameters: - name: organisationId @@ -1120,30 +1091,29 @@ paths: required: true schema: type: string - - $ref: "#/components/parameters/include" + - $ref: '#/components/parameters/include' get: - summary: Returns all versions of a particular phenotype or category in a repository. operationId: getEntityVersionsById - tags: - - entity + summary: Returns all versions of a particular phenotype or category in a repository. responses: - 200: + '200': description: List of versions. content: application/json: schema: type: array items: - $ref: "#/components/schemas/Entity" - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + $ref: '#/components/schemas/Entity' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' default: - $ref: "#/components/responses/UnexpectedError" - - /{organisationId}/{repositoryId}/{id}/subclasses: - summary: Represents subclasses (categories, abstract or restricted phenotypes) of an entity in a repository. + $ref: '#/components/responses/UnexpectedError' + tags: + - entity + '/{organisationId}/{repositoryId}/{id}/subclasses': + summary: 'Represents subclasses (categories, abstract or restricted phenotypes) of an entity in a repository.' parameters: - name: organisationId in: path @@ -1160,110 +1130,74 @@ paths: required: true schema: type: string - - $ref: "#/components/parameters/include" + - $ref: '#/components/parameters/include' get: - summary: Returns all subclasses of a particular phenotype or category in the repository. operationId: getSubclassesById - tags: - - entity + summary: Returns all subclasses of a particular phenotype or category in the repository. responses: - 200: + '200': description: List of subclasses. content: application/json: schema: type: array items: - $ref: "#/components/schemas/Entity" - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + $ref: '#/components/schemas/Entity' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' default: - $ref: "#/components/responses/UnexpectedError" - + $ref: '#/components/responses/UnexpectedError' + tags: + - entity /expression_function: parameters: - name: type in: query - description: > - Optional parameter to restrict the result set to a specific function type. - Currently, 'math' and 'boolean' are supported. + description: | + Optional parameter to restrict the result set to a specific function type. Currently, 'math' and 'boolean' are supported. schema: type: string get: - summary: Get all supported expression functions. operationId: getExpressionFunctions - tags: - - expression_function + summary: Get all supported expression functions. responses: - 200: + '200': description: List of supported expression functions. content: application/json: schema: type: array items: - $ref: "#/components/schemas/ExpressionFunction" - 401: - $ref: "#/components/responses/Unauthorized" + $ref: '#/components/schemas/ExpressionFunction' + '401': + $ref: '#/components/responses/Unauthorized' default: - $ref: "#/components/responses/UnexpectedError" - + $ref: '#/components/responses/UnexpectedError' + tags: + - expression_function /expression_constant: get: - summary: Get all supported expression constants. operationId: getExpressionConstants - tags: - - expression_constant + summary: Get all supported expression constants. responses: - 200: + '200': description: List of supported expression constants. content: application/json: schema: type: array items: - $ref: "#/components/schemas/Constant" - 401: - $ref: "#/components/responses/Unauthorized" + $ref: '#/components/schemas/Constant' + '401': + $ref: '#/components/responses/Unauthorized' default: - $ref: "#/components/responses/UnexpectedError" - + $ref: '#/components/responses/UnexpectedError' + tags: + - expression_constant components: - responses: - NotFound: - description: The specified resource was not found. - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - - Unauthorized: - description: Unauthorized, Access token is missing or invalid. - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - - UnexpectedError: - description: Unexpected error. - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - parameters: - page: - name: page - in: query - description: The desired page, if the result set is paged. - schema: - type: integer - format: int32 - minimum: 1 - default: 1 - include: name: include description: This field has no purpose jet. @@ -1272,13 +1206,19 @@ components: type: array items: type: string - pattern: '^\w*$' - + pattern: ^\w*$ + page: + name: page + in: query + description: 'The desired page, if the result set is paged.' + schema: + type: integer + format: int32 + default: 1 + minimum: 1 schemas: Repository: type: object - required: - - id properties: id: type: string @@ -1297,12 +1237,11 @@ components: type: string format: date-time organisation: - $ref: "#/components/schemas/Organisation" - - Ontology: - type: object + $ref: '#/components/schemas/Organisation' required: - id + Ontology: + type: object properties: id: type: string @@ -1311,16 +1250,15 @@ components: description: type: string repository: - $ref: "#/components/schemas/Repository" + $ref: '#/components/schemas/Repository' organisation: - $ref: "#/components/schemas/Organisation" + $ref: '#/components/schemas/Organisation' allOf: - - $ref: "#/components/schemas/VersionedContent" - - Organisation: - type: object + - $ref: '#/components/schemas/VersionedContent' required: - id + Organisation: + type: object properties: id: type: string @@ -1335,31 +1273,30 @@ components: type: string format: date-time superOrganisation: - $ref: "#/components/schemas/Organisation" - + $ref: '#/components/schemas/Organisation' + required: + - id Entity: description: Either category or phenotype. type: object - required: - - entityType properties: entityType: - $ref: "#/components/schemas/EntityType" + $ref: '#/components/schemas/EntityType' id: type: string titles: - type: array description: There should only be one title per language. + type: array items: - $ref: "#/components/schemas/LocalisableText" + $ref: '#/components/schemas/LocalisableText' synonyms: type: array items: - $ref: "#/components/schemas/LocalisableText" + $ref: '#/components/schemas/LocalisableText' descriptions: type: array items: - $ref: "#/components/schemas/LocalisableText" + $ref: '#/components/schemas/LocalisableText' index: type: integer format: int32 @@ -1368,47 +1305,46 @@ components: description: E.g. LOINC or ICD-10 codes. type: array items: - $ref: "#/components/schemas/Code" + $ref: '#/components/schemas/Code' repository: - $ref: "#/components/schemas/Repository" + $ref: '#/components/schemas/Repository' equivalentEntities: type: array items: - $ref: "#/components/schemas/Entity" + $ref: '#/components/schemas/Entity' allOf: - - $ref: "#/components/schemas/VersionedContent" + - $ref: '#/components/schemas/VersionedContent' discriminator: propertyName: entityType mapping: - category: "#/components/schemas/Category" - single_phenotype: "#/components/schemas/Phenotype" - composite_phenotype: "#/components/schemas/Phenotype" - single_restriction: "#/components/schemas/Phenotype" - composite_restriction: "#/components/schemas/Phenotype" - + category: '#/components/schemas/Category' + single_phenotype: '#/components/schemas/Phenotype' + composite_phenotype: '#/components/schemas/Phenotype' + single_restriction: '#/components/schemas/Phenotype' + composite_restriction: '#/components/schemas/Phenotype' + required: + - entityType Category: type: object properties: superCategories: type: array items: - $ref: "#/components/schemas/Category" + $ref: '#/components/schemas/Category' subCategories: type: array items: - $ref: "#/components/schemas/Category" + $ref: '#/components/schemas/Category' phenotypes: type: array items: - $ref: "#/components/schemas/Phenotype" + $ref: '#/components/schemas/Phenotype' allOf: - - $ref: "#/components/schemas/Entity" - + - $ref: '#/components/schemas/Entity' ItemType: + description: | + Only relevant for single phenotypes. This property specifies the class of items the phenotype holding this property belongs to. type: string - description: > - Only relevant for single phenotypes. - This property specifies the class of items the phenotype holding this property belongs to. enum: - allergy_intolerance - clinical_impression @@ -1420,64 +1356,59 @@ components: - procedure - subject_age - subject_sex - Phenotype: type: object properties: dataType: - $ref: "#/components/schemas/DataType" + $ref: '#/components/schemas/DataType' itemType: - $ref: "#/components/schemas/ItemType" + $ref: '#/components/schemas/ItemType' restriction: - $ref: "#/components/schemas/Restriction" + $ref: '#/components/schemas/Restriction' expression: - $ref: "#/components/schemas/Expression" + $ref: '#/components/schemas/Expression' unit: type: string minLength: 1 superPhenotype: - $ref: "#/components/schemas/Phenotype" + $ref: '#/components/schemas/Phenotype' allOf: - - $ref: "#/components/schemas/Category" - + - $ref: '#/components/schemas/Category' Constant: type: object - required: - - id - - dataType properties: id: - type: string description: A unique identifier of the constant. - title: type: string + title: description: Human-readable title of the constant. + type: string dataType: - $ref: "#/components/schemas/DataType" + $ref: '#/components/schemas/DataType' discriminator: propertyName: dataType mapping: - string: "#/components/schemas/StringConstant" - number: "#/components/schemas/NumberConstant" - date_time: "#/components/schemas/DateTimeConstant" - boolean: "#/components/schemas/BooleanConstant" - + string: '#/components/schemas/StringConstant' + number: '#/components/schemas/NumberConstant' + date_time: '#/components/schemas/DateTimeConstant' + boolean: '#/components/schemas/BooleanConstant' + required: + - id + - dataType StringConstant: type: object properties: value: type: string allOf: - - $ref: "#/components/schemas/Constant" - + - $ref: '#/components/schemas/Constant' NumberConstant: type: object properties: value: type: number allOf: - - $ref: "#/components/schemas/Constant" - + - $ref: '#/components/schemas/Constant' DateTimeConstant: type: object properties: @@ -1485,83 +1416,74 @@ components: type: string format: x-local-date-time allOf: - - $ref: "#/components/schemas/Constant" - + - $ref: '#/components/schemas/Constant' BooleanConstant: type: object properties: value: type: boolean allOf: - - $ref: "#/components/schemas/Constant" - + - $ref: '#/components/schemas/Constant' Expression: type: object properties: functionId: - type: string description: ID of a valid expression function. See ExpressionFunction for a detailed description. + type: string entityId: + description: 'In case this expression holds an entity, this property contains the id of that entity.' type: string - description: In case this expression holds an entity, this property contains the id of that entity. constantId: - type: string description: ID of a valid constant. See Constant for a detailed description. + type: string value: - $ref: "#/components/schemas/Value" + $ref: '#/components/schemas/Value' arguments: type: array items: - $ref: "#/components/schemas/Expression" + $ref: '#/components/schemas/Expression' values: + description: | + This property is for internal use only and will be ignored, if sent to a server. Items of this array property can hold results of function calls contained in expressions. type: array - description: > - This property is for internal use only and will be ignored, if sent to a server. - Items of this array property can hold results of function calls contained in expressions. items: - $ref: "#/components/schemas/Value" + $ref: '#/components/schemas/Value' restriction: - description: > - This property is for internal use only and will be ignored, if sent to a server. - Restrictions can be stored in this property to simplify the construction of phenotypic queries. - $ref: "#/components/schemas/Restriction" - + description: | + This property is for internal use only and will be ignored, if sent to a server. Restrictions can be stored in this property to simplify the construction of phenotypic queries. + $ref: '#/components/schemas/Restriction' Value: - required: - - dataType properties: dataType: - $ref: "#/components/schemas/DataType" + $ref: '#/components/schemas/DataType' dateTime: - description: > - This property is for internal use only and will be ignored, if sent to a server. - This property specifies when a value has been observed. + description: | + This property is for internal use only and will be ignored, if sent to a server. This property specifies when a value has been observed. type: string format: x-local-date-time discriminator: propertyName: dataType mapping: - string: "#/components/schemas/StringValue" - number: "#/components/schemas/NumberValue" - date_time: "#/components/schemas/DateTimeValue" - boolean: "#/components/schemas/BooleanValue" - + string: '#/components/schemas/StringValue' + number: '#/components/schemas/NumberValue' + date_time: '#/components/schemas/DateTimeValue' + boolean: '#/components/schemas/BooleanValue' + required: + - dataType StringValue: type: object properties: value: type: string allOf: - - $ref: "#/components/schemas/Value" - + - $ref: '#/components/schemas/Value' NumberValue: type: object properties: value: type: number allOf: - - $ref: "#/components/schemas/Value" - + - $ref: '#/components/schemas/Value' DateTimeValue: type: object properties: @@ -1569,89 +1491,80 @@ components: type: string format: x-local-date-time allOf: - - $ref: "#/components/schemas/Value" - + - $ref: '#/components/schemas/Value' BooleanValue: type: object properties: value: type: boolean allOf: - - $ref: "#/components/schemas/Value" - + - $ref: '#/components/schemas/Value' ExpressionFunction: type: object - required: - - id properties: id: - type: string description: The identifier of the function. Should be unique. + type: string example: add title: - type: string description: Human-readable title of the function. + type: string example: + notation: + description: | + This property defines the preferred notation of a function. If the property is missing or undefined, it should be treated as prefix. type: string + default: prefix enum: - prefix - infix - postfix - default: prefix - description: > - This property defines the preferred notation of a function. - If the property is missing or undefined, it should be treated as prefix. minArgumentNumber: + description: | + Determines how many arguments are at least required for this function. If this property is missing, the minimum argument number is unrestricted. type: integer format: int32 - description: > - Determines how many arguments are at least required for this function. - If this property is missing, the minimum argument number is unrestricted. maxArgumentNumber: + description: | + Determines how many arguments are allowed for this function at max. If this property is missing, the maximum argument number is unrestricted. type: integer format: int32 - description: > - Determines how many arguments are allowed for this function at max. - If this property is missing, the maximum argument number is unrestricted. - + required: + - id ForkingInstruction: type: object - required: - - organisationId - - repositoryId properties: organisationId: - type: string description: Destination organisation where fork will be created. - repositoryId: type: string + repositoryId: description: Destination repository where fork will be created. + type: string cascade: + description: Whether all sub entities shall be forked too. type: boolean default: false - description: Whether all sub entities shall be forked too. update: + description: Whether existing forks shall be updated to the newest version. type: boolean default: false - description: Whether existing forks shall be updated to the newest version. - + required: + - organisationId + - repositoryId ForkingStats: type: object properties: origin: - $ref: "#/components/schemas/Entity" + $ref: '#/components/schemas/Entity' forks: type: array items: - $ref: "#/components/schemas/Entity" - + $ref: '#/components/schemas/Entity' VersionNumber: description: Reflects the version of the content. The value is generated server-side. type: integer format: int32 minimum: 0 - EntityType: type: string enum: @@ -1660,16 +1573,18 @@ components: - composite_phenotype - single_restriction - composite_restriction - DataType: type: string - enum: [string, number, boolean, date_time] - + enum: + - string + - number + - boolean + - date_time VersionedContent: type: object properties: version: - $ref: "#/components/schemas/VersionNumber" + $ref: '#/components/schemas/VersionNumber' author: type: string createdAt: @@ -1678,13 +1593,9 @@ components: refer: type: string format: uri - LocalisableText: description: A text in a specific language. type: object - required: - - lang - - text properties: lang: description: ICU Locale code. @@ -1693,58 +1604,56 @@ components: text: description: The actual localised text. type: string - + required: + - lang + - text CodeSystem: type: object - required: - - uri - - name properties: uri: type: string format: uri name: type: string - + required: + - uri + - name Code: description: Code of a code system. type: object - required: - - codeSystem - - code properties: codeSystem: - $ref: "#/components/schemas/CodeSystem" + $ref: '#/components/schemas/CodeSystem' code: type: string name: type: string - + required: + - codeSystem + - code Restriction: description: Represents restriction of an abstract phenotype. type: object - required: - - type properties: type: - $ref: "#/components/schemas/DataType" + $ref: '#/components/schemas/DataType' quantifier: - $ref: "#/components/schemas/Quantifier" + $ref: '#/components/schemas/Quantifier' cardinality: - description: > - This value can be used in combination with a quantifier to specify - how many matches are required to fulfil this restriction. + description: | + This value can be used in combination with a quantifier to specify how many matches are required to fulfil this restriction. type: integer format: int32 minimum: 0 discriminator: propertyName: type mapping: - string: "#/components/schemas/StringRestriction" - number: "#/components/schemas/NumberRestriction" - date_time: "#/components/schemas/DateTimeRestriction" - boolean: "#/components/schemas/BooleanRestriction" - + string: '#/components/schemas/StringRestriction' + number: '#/components/schemas/NumberRestriction' + date_time: '#/components/schemas/DateTimeRestriction' + boolean: '#/components/schemas/BooleanRestriction' + required: + - type StringRestriction: type: object properties: @@ -1753,8 +1662,7 @@ components: items: type: string allOf: - - $ref: "#/components/schemas/Restriction" - + - $ref: '#/components/schemas/Restriction' BooleanRestriction: type: object properties: @@ -1763,51 +1671,45 @@ components: items: type: boolean allOf: - - $ref: "#/components/schemas/Restriction" - + - $ref: '#/components/schemas/Restriction' NumberRestriction: type: object properties: minOperator: - $ref: "#/components/schemas/RestrictionOperator" + $ref: '#/components/schemas/RestrictionOperator' maxOperator: - $ref: "#/components/schemas/RestrictionOperator" + $ref: '#/components/schemas/RestrictionOperator' values: + description: | + In case there are operators, the first two values are used as values for these operators. Convention: The first array item will always be treated as minimum and the second one as maximum. In case there is only a maximum value, the first array item is null. type: array - description: > - In case there are operators, the first two values are used as values for these operators. - Convention: - The first array item will always be treated as minimum and the second one as maximum. - In case there is only a maximum value, the first array item is null. items: type: number allOf: - - $ref: "#/components/schemas/Restriction" - + - $ref: '#/components/schemas/Restriction' DateTimeRestriction: type: object properties: minOperator: - $ref: "#/components/schemas/RestrictionOperator" + $ref: '#/components/schemas/RestrictionOperator' maxOperator: - $ref: "#/components/schemas/RestrictionOperator" + $ref: '#/components/schemas/RestrictionOperator' values: + description: | + In case there are operators, the first two values are used as values for these operators. Convention: The first array item will always be treated as minimum and the second one as maximum. In case there is only a maximum value, the first array item is null. type: array - description: > - In case there are operators, the first two values are used as values for these operators. - Convention: - The first array item will always be treated as minimum and the second one as maximum. - In case there is only a maximum value, the first array item is null. items: type: string format: x-local-date-time allOf: - - $ref: "#/components/schemas/Restriction" - + - $ref: '#/components/schemas/Restriction' RestrictionOperator: type: string - enum: ["<", "<=", ">", ">="] - + enum: + - < + - <= + - '>' + - '>=' Quantifier: type: string enum: @@ -1815,48 +1717,40 @@ components: - exact - min - max - Query: - description: > - Represents a search query for subjects/individuals. - A query has basic configurations for data source connections as well as in/exclusions and projections. + description: | + Represents a search query for subjects/individuals. A query has basic configurations for data source connections as well as in/exclusions and projections. type: object - required: - - id properties: id: type: string format: uuid name: - description: > - Name of this query. For example, you could allow users to save a query - for later use and use the name as identifier. + description: | + Name of this query. For example, you could allow users to save a query for later use and use the name as identifier. type: string dataSources: type: array items: - $ref: "#/components/schemas/DataSource" + $ref: '#/components/schemas/DataSource' criteria: description: List of in- and exclusion criteria. type: array items: - $ref: "#/components/schemas/QueryCriterion" + $ref: '#/components/schemas/QueryCriterion' projection: - description: > - The projection to be performed on the result set. - This property holds an ordered list of subjects with sorting directions. + description: | + The projection to be performed on the result set. This property holds an ordered list of subjects with sorting directions. type: array items: - $ref: "#/components/schemas/ProjectionEntry" + $ref: '#/components/schemas/ProjectionEntry' dependentSubjects: - $ref: "#/components/schemas/DependentSubjectsMap" - + $ref: '#/components/schemas/DependentSubjectsMap' + required: + - id QueryResult: description: Result of a query. It might indicate that the query has not finished yet or has failed. type: object - required: - - id - - createdAt properties: id: type: string @@ -1875,8 +1769,10 @@ components: description: Optional message about the query or query result. (e.g. error message) type: string state: - $ref: "#/components/schemas/QueryState" - + $ref: '#/components/schemas/QueryState' + required: + - id + - createdAt QueryState: type: string enum: @@ -1884,93 +1780,81 @@ components: - finished - queued - running - DependentSubjectsMap: - description: Map of additional subjects that hold information, required to execute the query. + description: 'Map of additional subjects that hold information, required to execute the query.' type: object - required: - - id properties: id: - type: string description: ID of the dependent subject. + type: string additionalProperties: - $ref: "#/components/schemas/Phenotype" - + $ref: '#/components/schemas/Phenotype' + required: + - id DataSource: description: A data source is a data storage (e.g. database) on which queries can be executed. type: object - required: - - id properties: id: - type: string description: ID of the data source. - title: type: string + title: description: Human-readable title of the data source. - + type: string + required: + - id QueryCriterion: description: A single criterion of a search query. Criteria can be inclusions or exclusions. type: object - required: - - subjectId - - inclusion - - defaultAggregationFunction properties: subjectId: - type: string description: ID of the subject this criterion refers to. + type: string inclusion: type: boolean default: true defaultAggregationFunctionId: + description: | + Multiple phenotype values in expressions must be aggregated to a single value in order to use them for calculations. The aggregation function provided via this property will be used as default aggregation function for cases where none has been set. type: string - description: > - Multiple phenotype values in expressions must be aggregated to - a single value in order to use them for calculations. - The aggregation function provided via this property will be used as - default aggregation function for cases where none has been set. dateTimeRestriction: - $ref: "#/components/schemas/DateTimeRestriction" - + $ref: '#/components/schemas/DateTimeRestriction' + required: + - subjectId + - inclusion + - defaultAggregationFunction ProjectionEntry: description: Single entry of a projection select list. type: object - required: - - subjectId - - sorting properties: subjectId: - type: string description: ID of a subject this projection entry refers to. + type: string sorting: - $ref: "#/components/schemas/Sorting" + $ref: '#/components/schemas/Sorting' dateTimeRestriction: - $ref: "#/components/schemas/DateTimeRestriction" - + $ref: '#/components/schemas/DateTimeRestriction' + required: + - subjectId + - sorting Sorting: type: string enum: - asc - desc - ErrorResponse: type: object - required: - - code - - message properties: code: type: integer format: int32 message: type: string - + required: + - code + - message Statistic: - description: - Holds statistics about content. The scope may be a subset of content stored on the server. - Statistics may vary depending on user permissions. + description: Holds statistics about content. The scope may be a subset of content stored on the server. Statistics may vary depending on user permissions. type: object properties: organisations: @@ -1989,17 +1873,34 @@ components: description: Number of phenotypes. type: integer format: int64 - Document: type: object - required: - - id properties: id: type: string text: type: string - + required: + - id + responses: + NotFound: + description: The specified resource was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + Unauthorized: + description: 'Unauthorized, Access token is missing or invalid.' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + UnexpectedError: + description: Unexpected error. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' securitySchemes: BearerAuth: type: http @@ -2008,7 +1909,6 @@ components: BasicAuth: type: http scheme: basic - security: - BearerAuth: [] - BasicAuth: [] From f927457a5ea8f116deb066da51a6c3933d5a4742 Mon Sep 17 00:00:00 2001 From: Christoph Beger Date: Thu, 13 Oct 2022 10:33:22 +0200 Subject: [PATCH 03/12] Reformat and improve README.md --- README.md | 71 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 38 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 7cee69b..f4c3bc7 100644 --- a/README.md +++ b/README.md @@ -5,14 +5,45 @@ This repository contains the OpenAPI 3 specification of the TOP framework. The s [![Publish snapshots](https://github.com/Onto-Med/top-api/actions/workflows/publish-snapshots.yml/badge.svg)](https://github.com/Onto-Med/top-api/actions/workflows/publish-snapshots.yml) [![Publish packages and create release](https://github.com/Onto-Med/top-api/actions/workflows/release.yml/badge.svg)](https://github.com/Onto-Med/top-api/actions/workflows/release.yml) +## Usage + +### Spring Boot Skeleton + +1. Add maven dependency + ```xml + + care.smith.top + top-api + + + ``` +2. Add annotation `@ComponentScan("care.smith.top.backend")` to your application class. +3. Create implementations for the delegate interfaces in `care.smith.top.backend.api` (e.g., `EntityApiDelegate`). + +### Typescript Axios + +1. Add the file .npmrc to the project folder, with the following content: + ```properties + @onto-med:registry=https://npm.pkg.github.com + ``` +2. Authenticate at GitHub Packages registry (you will be prompted for username and password aka. personal access token): + ```sh + npm login --scope=@onto-med --registry=https://npm.pkg.github.com + ``` +3. Add `@onto-med/top-api` as dependency, e.g.: + ```sh + yarn add @onto-med/top-api + ``` + +## Versioning + +There will always be a snapshot version available with latest changes pushed to the main branch. Snapshots have a **higher** version number than the latest release. + ## Development We recommend to use a [Visual Studie Code](https://code.visualstudio.com) [devcontainer](https://code.visualstudio.com/docs/remote/containers) to modify the specification file. The container has the [OpenAPI (Swagger) Editor](https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi) extension preinstalled. -Create new releases via GitHub Workflow [publish-snapshots.yml](.github/workflows/publish-snapshots.yml). Doing so will automaticaly build and publish a new Spring Boot skeleton package, generated with [https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator-maven-plugin](openapi-generator-maven-plugin). -Please update the version number in the [pom.xml](pom.xml) and [schemas/top-api.yml](schemas/top-api.yml) files **after** publishing a release. - ### Format Schema File You can use the npm package [openapi-format](https://www.npmjs.com/package/openapi-format) to automatically format the OpenApi schema file. @@ -21,36 +52,10 @@ You can use the npm package [openapi-format](https://www.npmjs.com/package/opena npx openapi-format schemas/top-api.yml --output schemas/top-api.yml ``` -### Versioning +### Releases -There will always be a snapshot version available with latest changes pushed to the main branch. Snapshots have a higher version number than the last release. +Create new releases via GitHub Workflow [publish-snapshots.yml](.github/workflows/publish-snapshots.yml). Doing so will automatically build and publish a new Spring Boot skeleton and typescript-axios package, generated with [openapi-generator-maven-plugin](https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator-maven-plugin). -## Spring Boot Skeleton +## License -Usage of the skeleton in your Spring Boot application: - -1. Add maven dependency -```xml - - care.smith.top - top-api - - -``` -2. Add annotation `@ComponentScan("care.smith.top.backend")` to your application class. -3. Create implementations for the delegate interfaces in `de.uni_leipzig.imise.top.backend.api` (e.g., `CodeSystemApiDelegate`). - -## Typescript Axios - -1. Add the file .npmrc to the project folder, with the following content: -```properties -@onto-med:registry=https://npm.pkg.github.com -``` -2. Authenticate at GitHub Packages registry (you will be prompted for username and password aka. personal access token): -```sh -npm login --scope=@onto-med --registry=https://npm.pkg.github.com -``` -3. Add `@onto-med/top-api` as dependency, e.g.: -```sh -yarn add @onto-med/top-api -``` +The code in this repository and the packages `care.smith.top:top-api` and `@onto-med/top-api` are licensed under [GPL-3.0](LICENSE). \ No newline at end of file From 4c58fdc634af5d355bd34f66574597ea112259b8 Mon Sep 17 00:00:00 2001 From: Christoph Beger Date: Thu, 13 Oct 2022 10:34:36 +0200 Subject: [PATCH 04/12] Bump up version --- pom.xml | 2 +- schemas/top-api.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/pom.xml b/pom.xml index e79da86..e9638b3 100644 --- a/pom.xml +++ b/pom.xml @@ -4,7 +4,7 @@ care.smith.top top-api - 0.5.1 + 0.5.2 TOP API REST API of the TOP framework diff --git a/schemas/top-api.yml b/schemas/top-api.yml index 7e0708a..a1447bb 100644 --- a/schemas/top-api.yml +++ b/schemas/top-api.yml @@ -1,7 +1,7 @@ openapi: 3.0.0 info: title: TOP API - version: 0.5.1 + version: 0.5.2 description: 'API to manage phenotypes, repositories, ontologies and organisations and to execute phenotypic queries.' servers: - url: 'https://top.imise.uni-leipzig.de/api' From a6cdd3ef2f922732d738c107cca1f3db3fdbe521 Mon Sep 17 00:00:00 2001 From: Christoph Beger Date: Thu, 13 Oct 2022 11:37:55 +0200 Subject: [PATCH 05/12] Add postman documentation badge --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index f4c3bc7..9cc3bbe 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,7 @@ This repository contains the OpenAPI 3 specification of the TOP framework. The s [![Publish snapshots](https://github.com/Onto-Med/top-api/actions/workflows/publish-snapshots.yml/badge.svg)](https://github.com/Onto-Med/top-api/actions/workflows/publish-snapshots.yml) [![Publish packages and create release](https://github.com/Onto-Med/top-api/actions/workflows/release.yml/badge.svg)](https://github.com/Onto-Med/top-api/actions/workflows/release.yml) +[![Postman](https://img.shields.io/badge/Postman-FF6C37?style=flat&logo=postman&logoColor=white)](https://documenter.getpostman.com/view/23852272/2s83zpHzmd) ## Usage @@ -58,4 +59,4 @@ Create new releases via GitHub Workflow [publish-snapshots.yml](.github/workflow ## License -The code in this repository and the packages `care.smith.top:top-api` and `@onto-med/top-api` are licensed under [GPL-3.0](LICENSE). \ No newline at end of file +The code in this repository and the packages `care.smith.top:top-api` and `@onto-med/top-api` are licensed under [GPL-3.0](LICENSE). From b498eae80c4c10e5f85d42ec98171b9bebc631cd Mon Sep 17 00:00:00 2001 From: Christoph Beger Date: Thu, 13 Oct 2022 13:18:50 +0200 Subject: [PATCH 06/12] Create CODE_OF_CONDUCT.md --- CODE_OF_CONDUCT.md | 128 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 CODE_OF_CONDUCT.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..39d8b5e --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,128 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity +and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or + advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement. +Feel free to contact them via their GitHub handle. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series +of actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or +permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within +the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.0, available at +https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct +enforcement ladder](https://github.com/mozilla/diversity). + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see the FAQ at +https://www.contributor-covenant.org/faq. Translations are available at +https://www.contributor-covenant.org/translations. From feaaeda5a7872d581d868cdf2882492bbdd7d379 Mon Sep 17 00:00:00 2001 From: Christoph Beger Date: Fri, 14 Oct 2022 15:49:58 +0200 Subject: [PATCH 07/12] Only store data source IDs in queries --- schemas/top-api.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/schemas/top-api.yml b/schemas/top-api.yml index a1447bb..aa4f007 100644 --- a/schemas/top-api.yml +++ b/schemas/top-api.yml @@ -1730,9 +1730,10 @@ components: Name of this query. For example, you could allow users to save a query for later use and use the name as identifier. type: string dataSources: + description: List of data source IDs. type: array items: - $ref: '#/components/schemas/DataSource' + type: string criteria: description: List of in- and exclusion criteria. type: array From 54b8fd5d9a347d8ee141c9372e0ab78c00b8d070 Mon Sep 17 00:00:00 2001 From: Christoph Beger Date: Mon, 17 Oct 2022 06:05:41 +0000 Subject: [PATCH 08/12] Drop unused properties --- schemas/top-api.yml | 21 --------------------- 1 file changed, 21 deletions(-) diff --git a/schemas/top-api.yml b/schemas/top-api.yml index aa4f007..0d75c06 100644 --- a/schemas/top-api.yml +++ b/schemas/top-api.yml @@ -1297,10 +1297,6 @@ components: type: array items: $ref: '#/components/schemas/LocalisableText' - index: - type: integer - format: int32 - minimum: 1 codes: description: E.g. LOINC or ICD-10 codes. type: array @@ -1341,28 +1337,11 @@ components: $ref: '#/components/schemas/Phenotype' allOf: - $ref: '#/components/schemas/Entity' - ItemType: - description: | - Only relevant for single phenotypes. This property specifies the class of items the phenotype holding this property belongs to. - type: string - enum: - - allergy_intolerance - - clinical_impression - - condition - - medication_administration - - medication_request - - medication_statement - - observation - - procedure - - subject_age - - subject_sex Phenotype: type: object properties: dataType: $ref: '#/components/schemas/DataType' - itemType: - $ref: '#/components/schemas/ItemType' restriction: $ref: '#/components/schemas/Restriction' expression: From 8466b5e9f1f7add240ac3166072dc7705e793b74 Mon Sep 17 00:00:00 2001 From: Christoph Beger Date: Mon, 28 Nov 2022 10:59:34 +0100 Subject: [PATCH 09/12] Add bulk upload endpoint --- schemas/top-api.yml | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/schemas/top-api.yml b/schemas/top-api.yml index 0d75c06..a60b8e4 100644 --- a/schemas/top-api.yml +++ b/schemas/top-api.yml @@ -798,6 +798,42 @@ paths: $ref: '#/components/responses/UnexpectedError' tags: - entity + '/{organisationId}/{repositoryId}/entity/bulk': + parameters: + - name: organisationId + in: path + required: true + schema: + type: string + - name: repositoryId + in: path + required: true + schema: + type: string + - $ref: '#/components/parameters/include' + post: + operationId: bulkUploadEntities + summary: Creates multiple new phenotypes or categories in a repository. + requestBody: + description: List of phenotypes or categories to be created. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Entity' + required: true + responses: + '200': + description: Entities have been created. + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' + default: + $ref: '#/components/responses/UnexpectedError' + tags: + - entity '/{organisationId}/{repositoryId}/root': parameters: - name: organisationId From e3a09f39d72f68df5bccaba12453b4e2239909ff Mon Sep 17 00:00:00 2001 From: Christoph Beger Date: Mon, 28 Nov 2022 11:01:09 +0100 Subject: [PATCH 10/12] Bump up version --- pom.xml | 2 +- schemas/top-api.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/pom.xml b/pom.xml index e9638b3..0cc0117 100644 --- a/pom.xml +++ b/pom.xml @@ -4,7 +4,7 @@ care.smith.top top-api - 0.5.2 + 0.5.3 TOP API REST API of the TOP framework diff --git a/schemas/top-api.yml b/schemas/top-api.yml index a60b8e4..318ff0a 100644 --- a/schemas/top-api.yml +++ b/schemas/top-api.yml @@ -1,7 +1,7 @@ openapi: 3.0.0 info: title: TOP API - version: 0.5.2 + version: 0.5.3 description: 'API to manage phenotypes, repositories, ontologies and organisations and to execute phenotypic queries.' servers: - url: 'https://top.imise.uni-leipzig.de/api' From f6d20b080dcb388ef266fe88ee2194cf75de9cc7 Mon Sep 17 00:00:00 2001 From: Christoph Beger Date: Mon, 28 Nov 2022 11:11:43 +0100 Subject: [PATCH 11/12] Update response status code of bulk upload --- schemas/top-api.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/schemas/top-api.yml b/schemas/top-api.yml index 318ff0a..4170cc3 100644 --- a/schemas/top-api.yml +++ b/schemas/top-api.yml @@ -824,7 +824,7 @@ paths: $ref: '#/components/schemas/Entity' required: true responses: - '200': + '201': description: Entities have been created. '401': $ref: '#/components/responses/Unauthorized' From b583852aa8339d799d6e7a16952e6d1fc9987ed1 Mon Sep 17 00:00:00 2001 From: Christoph Beger Date: Wed, 30 Nov 2022 14:51:00 +0100 Subject: [PATCH 12/12] Replace postman with github pages --- README.md | 2 +- index.html | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 48 insertions(+), 1 deletion(-) create mode 100644 index.html diff --git a/README.md b/README.md index 9cc3bbe..475ef89 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ This repository contains the OpenAPI 3 specification of the TOP framework. The s [![Publish snapshots](https://github.com/Onto-Med/top-api/actions/workflows/publish-snapshots.yml/badge.svg)](https://github.com/Onto-Med/top-api/actions/workflows/publish-snapshots.yml) [![Publish packages and create release](https://github.com/Onto-Med/top-api/actions/workflows/release.yml/badge.svg)](https://github.com/Onto-Med/top-api/actions/workflows/release.yml) -[![Postman](https://img.shields.io/badge/Postman-FF6C37?style=flat&logo=postman&logoColor=white)](https://documenter.getpostman.com/view/23852272/2s83zpHzmd) +[![Swagger UI](https://img.shields.io/badge/-Swagger%20UI-%23Clojure?style=flat&logo=swagger&logoColor=white)](https://onto-med.github.io/top-api/) ## Usage diff --git a/index.html b/index.html new file mode 100644 index 0000000..dbddddc --- /dev/null +++ b/index.html @@ -0,0 +1,47 @@ + + + + + + TOP API + + +
+ + + + \ No newline at end of file