add api yaml v1 #32

chinaunicomyangfan · 2024-06-27T16:06:16Z

What type of PR is this?

Add one of the following kinds:

documentation

What this PR does / why we need it:

add api yaml v1

add api yaml

hdamker

Please see my suggestion for compliance with the new API versioning and release process.

code/API_definitions/NetworkSliceBooking.yaml

ShutingQing · 2024-06-29T08:06:39Z

Thanks Herbert, we'll start the release process.

hdamker · 2024-07-01T06:49:23Z

Thanks Herbert, we'll start the release process.

@ShutingQing No rush needed, take first the time to have a work in progress version which is discussed within the team and agreed to be (pre-)released. The important point is that this PR here will create a "wip" version but not a version with a version number.

Note: I have not commented on the content of the PR.

Update API version to wip

tlohmar · 2024-07-01T07:40:59Z

code/API_definitions/NetworkSliceBooking.yaml

+        ServiceArea:
+          $ref: "#/components/schemas/Area"
+        SLAProfile:
+          $ref: "#/components/schemas/SLAProfile"


SLAProfile

I suggest to remove the prefix "SLA".
1: The area and the service time should be part of the SLA as well.
2: An SLA contains may other aspects, which are not handled by the API.

tlohmar · 2024-07-01T07:41:51Z

code/API_definitions/NetworkSliceBooking.yaml

+      properties:
+        MaxNumofTerminals:
+          $ref: "#/components/schemas/NumofTerminals"
+        DLThroughputPerTerminal:


What is the relation to the QOS Profiles, as developed by QOD Group?

tlohmar · 2024-07-01T07:43:04Z

code/API_definitions/NetworkSliceBooking.yaml

+      type: object
+      properties:
+        min:
+          $ref: "#/components/schemas/Float"


I suggest to simplify the yaml and use the type number directly. --> data type is number for format float

tlohmar · 2024-07-01T07:44:11Z

code/API_definitions/NetworkSliceBooking.yaml

+      maximum: 20
+
+
+    Throughput:


I suggest to allow unit prefixes like kilo or mega.

tlohmar · 2024-07-01T07:46:59Z

code/API_definitions/NetworkSliceBooking.yaml

+      type: object
+      properties:
+        StartTime:
+          $ref: "#/components/schemas/TimeStamp"


Do we really need a Data type for TimeStamp? It should be a simple string with a format date-time.

tlohmar · 2024-07-01T07:48:19Z

code/API_definitions/NetworkSliceBooking.yaml

+        EndTime:
+          $ref: "#/components/schemas/TimeStamp"
+
+    Float:


I suggest to remove the data-type and use the OpenAPI "number" data-type. See Section on Numbers

tlohmar · 2024-07-01T07:53:31Z

code/API_definitions/NetworkSliceBooking.yaml

+      maximum: 180
+
+    TimeStamp:
+      type: string


I suggest to add "format: date-time" (i.e. not just in the description).

code/API_definitions/NetworkSliceBooking.yaml

tlohmar · 2024-07-01T07:58:30Z

code/API_definitions/NetworkSliceBooking.yaml

+      type: array
+      items:
+        $ref: "#/components/schemas/Point"
+      minItems: 3


There should be a requirement, that the third point is not on the same line as the first two points.

As this area definition is used also in other APIs I suggest to bring the discussion to DeviceLocation and/or Commonalities. As a minimum requirement the polygon must not be self-intersecting.

Aha, yes, would be good to re-use data types (when possible). Likely the best to bring this discussion to Commonalities.

I opened an issue in commonalities (Issue 242)

code/API_definitions/NetworkSliceBooking.yaml

Requested formal changes done, but I haven't reviewed the content, hence can't approve it.

tlohmar

Some updates, specifically around the Area data type.

code/API_definitions/NetworkSliceBooking.yaml

Masa8106 · 2024-07-02T15:29:54Z

code/API_definitions/NetworkSliceBooking.yaml

+      description: Number of terminals
+      format: int32
+      minimum: 1
+      maximum: 20


Do you need to limit range with the maximum number of terminals which is 20? I would like to suggest to remove "maximum: 20".

"Maximum Num of Terminals" is suggested to keep it. This is an attribute that used to evaluation whether Network can assure the slice to be booked and meet the customers' need.

To keep the parameter "Maximum Num of Terminal" itself is fine with me. I wonder the reason to limit the number 20 (and not 30 or 50)?

ShutingQing · 2024-07-05T01:22:45Z

code/API_definitions/NetworkSliceBooking.yaml

@@ -0,0 +1,293 @@
+openapi: 3.0.3
+info:
+  title: API for Network slicing Booking


-> "API for Network Slice Booking"

ShutingQing · 2024-07-05T01:25:56Z

code/API_definitions/NetworkSliceBooking.yaml

+          schema:
+            $ref: "#/components/schemas/SessionId"
+      responses:
+        "204":


i believe we need some error code here, so as get session

ShutingQing · 2024-07-05T01:41:12Z

code/API_definitions/NetworkSliceBooking.yaml

+      type: integer
+      example: 10
+      description: |
+        An attribute specifies the required DL packet transmission latency (millisecond) 


We can use a common rate data type here.

ShutingQing

I left some comments, please check files changed. Thank you. : ）

ShutingQing · 2024-07-05T08:13:28Z

https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#6-error-responses

ShutingQing · 2024-07-05T08:26:45Z

code/API_definitions/NetworkSliceBooking.yaml

+      properties:
+        MaxNumofTerminals:
+          $ref: "#/components/schemas/NumofTerminals"
+        DLThroughputPerTerminal:


Each terminal should have different DL UP throughput.

ShutingQing · 2024-07-05T08:28:49Z

code/API_definitions/NetworkSliceBooking.yaml

+    NumofTerminals:
+      type: integer
+      example: 5
+      description: Number of terminals


Add some descriptions.

"Maximum Num of Terminals" is suggested to keep it. This is an attribute that used to evaluation whether Network can assure the slice to be booked and meet the customers' need.

Masa8106 · 2024-07-09T15:42:15Z

code/API_definitions/NetworkSliceBooking.yaml

+      description: Number of terminals
+      format: int32
+      minimum: 1
+      maximum: 20


One more thing. Just let me ask you.
Device access management is mentioned in api design #20.
In this PR, the API can specify the number of terminals but cannot specify which terminals will be allowed to access the slice.
Do you have a plan to add more parameter related to device access management or create new device access management API later?

Yes Masa, based on Thorsten's suggestion, we'd better need to make device access management function independently. Basically there is one slice resource reservation function, and another device access management function.

linux-foundation-easycla · 2024-09-04T10:30:09Z

The committers listed above are authorized under a signed CLA.

✅ login: chinaunicomyangfan / name: Fan Yang-ChinaUnicom (2609d37, f4b5633, 55a7fe3, 48e44f7, 8135cb2, ac6578c)

code/API_definitions/NetworkSliceBooking.yaml

hdamker · 2024-09-09T18:23:28Z

code/API_definitions/NetworkSliceBooking.yaml

+          $ref: "#/components/responses/Generic503"
+    get:
+      tags:
+        - NSB Sessions


Suggested change

- NSB Sessions

- Network Slice Booking Sessions

@ShutingQing you need to commit this suggestion as well, otherwise it doesn't fit to line 17

code/API_definitions/NetworkSliceBooking.yaml

hdamker

Some change requests and suggestions based on the Commonalities guidelines and templates to help being more compliant from the beginning.

ShutingQing · 2024-09-10T02:16:56Z

Thanks so much Herbert for the detailed suggestions attached. We'll look into it.

ShutingQing · 2024-09-20T02:51:28Z

Hi all. Based on the last meeting discussion, there were no further comments. Later for Herbert's suggestions, we've modified one version. Currently the version looks good to me. Please other reviewers take a look. If there is no further comments, we give this an approve.

tlohmar

Would be good to update the PullRequest and implement the comments. It is now a bit difficult to judge, how the various comments will modify the yaml.

tlohmar · 2024-09-20T07:28:21Z

code/API_definitions/NetworkSliceBooking.yaml

+    NumberOfTerminals:
+      type: integer
+      example: 5
+      description: Number of terminals


The term 'device' is used in other CAMARA APIs and I assume, that a 'terminal" is the same as a 'device'. When there is indeed no difference between 'terminal' and 'device', I suggest to use change to 'MaxNumberOfDevices' (or MaximumNumberOfDevices)..

The term 'device' is used in other CAMARA APIs and I assume, that a 'terminal" is the same as a 'device'. When there is indeed no difference between 'terminal' and 'device', I suggest to use change to 'MaxNumberOfDevices' (or MaximumNumberOfDevices)..

That's okay for me. Fan and me will modify this. For further comments, I'll suggest to initiate another issue and pr to keep updating the yaml.

hdamker

I suppose the YAML within this PR is now a good "work in progress" starting point for the further work within the repository and I recommend to merge it as soon as possible to allow to create issues for the further discussion needed.

@ShutingQing

... For further comments, I'll suggest to initiate another issue and pr to keep updating the yaml.

That can be done only after there is a yaml merged into main. Currently the base of the discussion is only this PR here.

And thanks for accepting my suggestions - I resolved the conversations. There was one overseen which needs to be committed as there is now no "NSB Sessions" tags defined anymore.

One point which you might want to consider already here or open as an issue (as it might need some discussion):

The schema which is now named as QoSProfile is something different than the resource definition QoSProfile within the qos-profile API in QualityOnDemand. I would also say that it isn't a QoS Profile (for a single device), but the parameters for the requested slice (see e.g. the parameter MaxNumofTerminals). So something like "SliceProfile" maybe?

chinaunicomyangfan added 2 commits June 27, 2024 23:17

a

2609d37

Merge pull request #1 from chinaunicomyangfan/addyamlv0.1

ac6578c

add api yaml

chinaunicomyangfan requested review from DanXu-ChinaTelecom and Kai-hw as code owners June 27, 2024 16:06

chinaunicomyangfan mentioned this pull request Jun 27, 2024

add api yaml v1 #33

Open

hdamker requested changes Jun 28, 2024

View reviewed changes

code/API_definitions/NetworkSliceBooking.yaml Outdated Show resolved Hide resolved

code/API_definitions/NetworkSliceBooking.yaml Outdated Show resolved Hide resolved

chinaunicomyangfan added 2 commits July 1, 2024 15:04

Update API version to wip

48e44f7

Merge pull request #2 from chinaunicomyangfan/addyamlv0.1

55a7fe3

Update API version to wip

ShutingQing requested a review from hdamker July 1, 2024 07:23

tlohmar reviewed Jul 1, 2024

View reviewed changes

hdamker previously approved these changes Jul 1, 2024

View reviewed changes

hdamker self-requested a review July 1, 2024 15:36

tlohmar reviewed Jul 2, 2024

View reviewed changes

code/API_definitions/NetworkSliceBooking.yaml Show resolved Hide resolved

code/API_definitions/NetworkSliceBooking.yaml Show resolved Hide resolved

Masa8106 reviewed Jul 2, 2024

View reviewed changes

ShutingQing reviewed Jul 5, 2024

View reviewed changes

Masa8106 reviewed Jul 9, 2024

View reviewed changes

Update NetworkSliceBooking.yaml

f4b5633

hdamker reviewed Sep 9, 2024

View reviewed changes

code/API_definitions/NetworkSliceBooking.yaml Outdated Show resolved Hide resolved

hdamker reviewed Sep 9, 2024

View reviewed changes

code/API_definitions/NetworkSliceBooking.yaml Outdated Show resolved Hide resolved

hdamker reviewed Sep 9, 2024

View reviewed changes

code/API_definitions/NetworkSliceBooking.yaml Outdated Show resolved Hide resolved

hdamker reviewed Sep 9, 2024

View reviewed changes

code/API_definitions/NetworkSliceBooking.yaml Outdated Show resolved Hide resolved

hdamker reviewed Sep 9, 2024

View reviewed changes

code/API_definitions/NetworkSliceBooking.yaml Outdated Show resolved Hide resolved

hdamker reviewed Sep 9, 2024

View reviewed changes

code/API_definitions/NetworkSliceBooking.yaml Outdated Show resolved Hide resolved

hdamker reviewed Sep 9, 2024

View reviewed changes

code/API_definitions/NetworkSliceBooking.yaml Outdated Show resolved Hide resolved

hdamker reviewed Sep 9, 2024

View reviewed changes

code/API_definitions/NetworkSliceBooking.yaml Show resolved Hide resolved

hdamker reviewed Sep 9, 2024

View reviewed changes

code/API_definitions/NetworkSliceBooking.yaml Show resolved Hide resolved

hdamker requested changes Sep 9, 2024

View reviewed changes

Update NetworkSliceBooking.yaml

8135cb2

ShutingQing requested a review from hdamker September 20, 2024 02:48

tlohmar reviewed Sep 20, 2024

View reviewed changes

hdamker approved these changes Sep 20, 2024

View reviewed changes

ShutingQing approved these changes Sep 23, 2024

View reviewed changes

Kai-hw closed this Sep 23, 2024

Kai-hw reopened this Sep 23, 2024

DanXu-ChinaTelecom approved these changes Sep 23, 2024

View reviewed changes

Kai-hw merged commit db60af9 into camaraproject:main Sep 23, 2024
1 check passed

hdamker mentioned this pull request Sep 23, 2024

Update NetworkSliceBooking.yaml - aligned tags #43

Open

add api yaml v1 #32

add api yaml v1 #32

Conversation

chinaunicomyangfan commented Jun 27, 2024

What type of PR is this?

What this PR does / why we need it:

hdamker left a comment

Choose a reason for hiding this comment

ShutingQing commented Jun 29, 2024

hdamker commented Jul 1, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tlohmar Jul 1, 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

tlohmar Jul 1, 2024 • edited Loading

Choose a reason for hiding this comment

tlohmar left a comment

Choose a reason for hiding this comment

Masa8106 Jul 2, 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

ShutingQing left a comment

Choose a reason for hiding this comment

ShutingQing commented Jul 5, 2024

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

linux-foundation-easycla bot commented Sep 4, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hdamker left a comment • edited Loading

Choose a reason for hiding this comment

ShutingQing commented Sep 10, 2024

ShutingQing commented Sep 20, 2024

tlohmar left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hdamker left a comment • edited Loading

Choose a reason for hiding this comment

hdamker commented Jul 1, 2024 •

edited

Loading

tlohmar Jul 1, 2024 •

edited

Loading

tlohmar Jul 1, 2024 •

edited

Loading

Masa8106 Jul 2, 2024 •

edited

Loading

linux-foundation-easycla bot commented Sep 4, 2024 •

edited

Loading

hdamker left a comment •

edited

Loading

hdamker left a comment •

edited

Loading