Adjust OpenAPI Files for Discovery Service Profiles #229

sebbader-sap · 2024-02-19T17:12:00Z

The names of the files did not match to the version (v3.1) in which they are going to be published.

BirgitBoss · 2024-02-20T10:04:43Z

DiscoveryServiceSpecification/V3.1_SSP-001.yaml

+  version: V3.1.0_SSP-001
+  x-profile-identifier: https://admin-shell.io/aas/API/3/1/DiscoveryServiceSpecification/SSP-001
+servers:
+- url: 'https://admin-shell.io/api/v3.1'


only v3 or v3.1 correct in this context?

Both are possible. I feel like "v3.1" is closer to the profile version. Doesn't really matter.

But it is a url? And we recommend in endpoints to just use major version

BirgitBoss · 2024-02-20T10:05:05Z

DiscoveryServiceSpecification/V3.1_SSP-001.yaml

+  x-profile-identifier: https://admin-shell.io/aas/API/3/1/DiscoveryServiceSpecification/SSP-001
+servers:
+- url: 'https://admin-shell.io/api/v3.1'
+- url: 'https://example.com/'


why two url?

To make clear that the "/api/v3.1" path segments are not mandatory.

DiscoveryServiceSpecification/V3.1_SSP-001.yaml

DiscoveryServiceSpecification/V3.0_SSP-001.yaml

BirgitBoss

V3.0_SSP-001.yaml is not identical to the corresponding file in release 3.0 but it should, no? Or is it V3.0.2?

BirgitBoss · 2024-02-20T10:18:43Z

We need to check versions of API-operations: will version increase to V3.1 if payload changed due to changes in Part 1? We need to check this.

Co-authored-by: Birgit Boss <[email protected]>

sebbader-sap · 2024-02-28T15:03:03Z

We need to check versions of API-operations: will version increase to V3.1 if payload changed due to changes in Part 1? We need to check this.

Yes, this is an unavoidable consequence: If Part 1 V3.1 is published, the SwaggerHub Domain Part 1 Version 3.1 will be created. As all SwaggerHub APIs, e.g., DiscoveryServiceSpecification V3.0.1, explicitly link to one and only one version of a Domain (for now Part 2 V3.0.1, which referencers Part 1 V3.0.1), we need to release a equivalent version (V3.1.0) for each API, too.

sebbader-sap · 2024-02-28T15:04:00Z

V3.0_SSP-001.yaml is not identical to the corresponding file in release 3.0 but it should, no? Or is it V3.0.2?

It should, or am I missing anything? See also my comment above.

BirgitBoss · 2024-03-04T12:33:45Z

Can you please add the milestone this PR belongs to?

BirgitBoss · 2024-03-04T12:37:55Z

DiscoveryServiceSpecification/V3.0_SSP-001.yaml

- url: 'https://admin-shell.io/api/v3.1'
- url: 'https://example.com/'
-
+- url: '{protocol}://{host_name}:{port}/api/{version_prefix}'


Didn't we decide to support very flexible URL, just {protocol}://{base-url}. + Text: We recommend to use major version of API version only. After version it is still possible that there is a tenant-ID or a different order...

This is 3.0.1 but 3.0.1 is already released: I am getting confused…

BirgitBoss · 2024-03-04T12:39:32Z

DiscoveryServiceSpecification/V3.0_SSP-001.yaml

      tags:
        - Asset Administration Shell Basic Discovery API
      summary: Returns a list of Asset Administration Shell ids linked to specific Asset identifiers 
      operationId: GetAllAssetAdministrationShellIdsByAssetLink
      x-semanticIds:
        - https://admin-shell.io/aas/API/GetAllAssetAdministrationShellIdsByAssetLink/3/0
      parameters:
-        - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/parameters/AssetIds'


why is this changed? I expected it to stay as it was?

This is 3,0

BirgitBoss · 2024-03-04T12:41:13Z

DiscoveryServiceSpecification/V3.0_SSP-001.yaml

-      tags:
-        - Asset Administration Shell Basic Discovery API
-      summary: Returns a list of Asset Administration Shell ids linked to specific Asset identifiers 
-      operationId: SearchAllAssetAdministrationShellIdsByAssetLink


why is this operation removed? it is the new one, no?

This is 3.0

BirgitBoss · 2024-03-04T12:42:47Z

DiscoveryServiceSpecification/V3.0_SSP-001.yaml

-        - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/parameters/AssetIds'
-        - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/parameters/Limit'
-        - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/parameters/Cursor'
+        - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.1#/components/parameters/AssetIds'


this is not parameter any longer but part of the request body

BirgitBoss · 2024-03-04T12:43:48Z

DiscoveryServiceSpecification/V3.1_SSP-001.yaml

+info:
+  title: DotAAS Part 2 | HTTP/REST | Discovery Service Specification (V3.1 Draft, not released)
+  description: >-
+    The entire Full Profile of the Discovery Service Specification as part of the [Specification of the Asset Administration Shell: Part 2](http://industrialdigitaltwin.org/en/content-hub).  


Suggested change

The entire Full Profile of the Discovery Service Specification as part of the [Specification of the Asset Administration Shell: Part 2](http://industrialdigitaltwin.org/en/content-hub).

The entire Full Profile of the Discovery Service Specification as part of the [Specification of the Asset Administration Shell: Part 2](https://industrialdigitaltwin.org/en/content-hub/aasspecifications).

BirgitBoss · 2024-03-04T12:47:57Z

DiscoveryServiceSpecification/V3.1_SSP-001.yaml

+        - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/parameters/Limit'
+        - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/parameters/Cursor'
+      requestBody:
+        description: A list of specific Asset identifiers


Suggested change

description: A list of specific Asset identifiers

description: A list of specific asset identifiers. Search for the global asset ID is supported by setting "name" to "globalAssetId" (see Constraint AASd-077).

BirgitBoss · 2024-03-04T12:48:35Z

DiscoveryServiceSpecification/V3.1_SSP-001.yaml

+                '$ref': 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/schemas/AssetLink'
+      responses:
+        '200':
+          description: Requested Asset Administration Shell ids


Suggested change

description: Requested Asset Administration Shell ids

description: Requested Asset Administration Shell IDs

BirgitBoss · 2024-03-04T12:49:24Z

DiscoveryServiceSpecification/V3.1_SSP-001.yaml

+    get:
+      tags:
+        - Asset Administration Shell Basic Discovery API
+      summary: Returns a list of specific Asset identifiers based on an Asset Administration Shell id to edit discoverable content


Suggested change

summary: Returns a list of specific Asset identifiers based on an Asset Administration Shell id to edit discoverable content

summary: Returns a list of specific asset identifiers based on an Asset Administration Shell ID to edit discoverable content. The global asset ID is returned as specific asset ID with "name" equal to "globalAssetId" (see Constraint AASd-077).

BirgitBoss · 2024-03-04T12:54:38Z

DiscoveryServiceSpecification/V3.1_SSP-001.yaml

+    post:
+      tags:
+        - Asset Administration Shell Basic Discovery API
+      summary: Creates specific Asset identifiers linked to an Asset Administration Shell to edit discoverable content


Suggested change

summary: Creates specific Asset identifiers linked to an Asset Administration Shell to edit discoverable content

summary: Creates specific asset identifiers linked to an Asset Administration Shell to edit discoverable content

BirgitBoss · 2024-03-04T12:54:51Z

DiscoveryServiceSpecification/V3.1_SSP-001.yaml

+        required: true
+      responses:
+        '201':
+          description: Specific Asset identifiers created successfully


Suggested change

description: Specific Asset identifiers created successfully

description: Specific asset identifiers created successfully

BirgitBoss · 2024-03-04T12:55:01Z

DiscoveryServiceSpecification/V3.1_SSP-001.yaml

+      x-semanticIds:
+        - https://admin-shell.io/aas/API/PostAllAssetLinksById/3/0
+      requestBody:
+        description: A list of specific Asset identifiers


Suggested change

description: A list of specific Asset identifiers

description: A list of specific asset identifiers

BirgitBoss

see minor improvements

BirgitBoss · 2024-04-09T14:03:51Z

DiscoveryServiceSpecification/V3.0_SSP-001.yaml

@@ -11,83 +11,62 @@ info:
  license: 
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/
-  version: V3.1.0_SSP-001
-  x-profile-identifier: https://admin-shell.io/aas/API/3/1/DiscoveryServiceSpecification/SSP-001
+  version: V3.0.1_SSP-001


Suggested change

version: V3.0.1_SSP-001

version: V3.1.0_SSP-001

It is now V3.1, no? But all changes are for V3.0.1 but you want to merge it to branch of V3.1?

sebbader-sap added 3 commits February 19, 2024 18:04

revert Discovery Service Specification v3.0_SSP-001

d32a416

add Discovery Service Specification V3.1_SSP-001 as own YAML file

8c20ccc

adjust name of Discovery Service Specification SSP-002

75fb204

sebbader-sap requested a review from BirgitBoss February 19, 2024 17:12

BirgitBoss reviewed Feb 20, 2024

View reviewed changes

DiscoveryServiceSpecification/V3.1_SSP-001.yaml Outdated Show resolved Hide resolved

BirgitBoss reviewed Feb 20, 2024

View reviewed changes

DiscoveryServiceSpecification/V3.0_SSP-001.yaml Show resolved Hide resolved

BirgitBoss requested changes Feb 20, 2024

View reviewed changes

Update DiscoveryServiceSpecification/V3.1_SSP-001.yaml

98ea35d

Co-authored-by: Birgit Boss <[email protected]>

BirgitBoss added this to the 3.1 milestone Mar 4, 2024

BirgitBoss reviewed Mar 4, 2024

View reviewed changes

BirgitBoss removed this from the 3.1 milestone Mar 4, 2024

BirgitBoss reviewed Mar 4, 2024

View reviewed changes

sebbader-sap added this to the 3.1 milestone Mar 12, 2024

BirgitBoss reviewed Apr 9, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Adjust OpenAPI Files for Discovery Service Profiles #229

Adjust OpenAPI Files for Discovery Service Profiles #229

sebbader-sap commented Feb 19, 2024 •

edited

Loading

BirgitBoss Feb 20, 2024

sebbader-sap Feb 26, 2024

BirgitBoss Mar 5, 2024

BirgitBoss Feb 20, 2024

sebbader-sap Feb 26, 2024

BirgitBoss left a comment

BirgitBoss commented Feb 20, 2024

sebbader-sap commented Feb 28, 2024

sebbader-sap commented Feb 28, 2024

BirgitBoss commented Mar 4, 2024

BirgitBoss Mar 4, 2024

BirgitBoss Mar 5, 2024 •

edited

Loading

BirgitBoss Mar 4, 2024

BirgitBoss Mar 5, 2024

BirgitBoss Mar 4, 2024

BirgitBoss Mar 5, 2024

BirgitBoss Mar 4, 2024

BirgitBoss Mar 5, 2024

BirgitBoss Mar 4, 2024

BirgitBoss Mar 4, 2024 •

edited

Loading

BirgitBoss Mar 4, 2024

BirgitBoss Mar 4, 2024 •

edited

Loading

BirgitBoss Mar 4, 2024

BirgitBoss Mar 4, 2024

BirgitBoss Mar 4, 2024

BirgitBoss left a comment

BirgitBoss Apr 9, 2024

BirgitBoss Apr 9, 2024 •

edited

Loading

	The entire Full Profile of the Discovery Service Specification as part of the [Specification of the Asset Administration Shell: Part 2](http://industrialdigitaltwin.org/en/content-hub).
	The entire Full Profile of the Discovery Service Specification as part of the [Specification of the Asset Administration Shell: Part 2](https://industrialdigitaltwin.org/en/content-hub/aasspecifications).

	description: A list of specific Asset identifiers
	description: A list of specific asset identifiers. Search for the global asset ID is supported by setting "name" to "globalAssetId" (see Constraint AASd-077).

	description: Requested Asset Administration Shell ids
	description: Requested Asset Administration Shell IDs

	summary: Returns a list of specific Asset identifiers based on an Asset Administration Shell id to edit discoverable content
	summary: Returns a list of specific asset identifiers based on an Asset Administration Shell ID to edit discoverable content. The global asset ID is returned as specific asset ID with "name" equal to "globalAssetId" (see Constraint AASd-077).

	summary: Creates specific Asset identifiers linked to an Asset Administration Shell to edit discoverable content
	summary: Creates specific asset identifiers linked to an Asset Administration Shell to edit discoverable content

	description: Specific Asset identifiers created successfully
	description: Specific asset identifiers created successfully

Adjust OpenAPI Files for Discovery Service Profiles #229

Are you sure you want to change the base?

Adjust OpenAPI Files for Discovery Service Profiles #229

Conversation

sebbader-sap commented Feb 19, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

BirgitBoss left a comment

Choose a reason for hiding this comment

BirgitBoss commented Feb 20, 2024

sebbader-sap commented Feb 28, 2024

sebbader-sap commented Feb 28, 2024

BirgitBoss commented Mar 4, 2024

Choose a reason for hiding this comment

BirgitBoss Mar 5, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

BirgitBoss Mar 4, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

BirgitBoss Mar 4, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

BirgitBoss left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

BirgitBoss Apr 9, 2024 • edited Loading

Choose a reason for hiding this comment

sebbader-sap commented Feb 19, 2024 •

edited

Loading

BirgitBoss Mar 5, 2024 •

edited

Loading

BirgitBoss Mar 4, 2024 •

edited

Loading

BirgitBoss Mar 4, 2024 •

edited

Loading

BirgitBoss Apr 9, 2024 •

edited

Loading