add api design

[ShutingQing]

What type of PR is this?

Add one of the following kinds:

• documentation

What this PR does / why we need it:

Add API Design.
Basically split "Get a Slice" function into 2 steps. One is reserve a slice. Another is manage the end service access control.

Which issue(s) this PR fixes:

Fixes #

Special notes for reviewers:

Changelog input

 release-note

Additional documentation

This section can be blank.

docs

[ShutingQing]

Please reviewers take a look in advance.

[tlohmar]

Generally, I am still not ok with the usage of the term 'slice', since it is against the CAMARA paradigm to hide telco complexity and allow the telco's to decide on the implementation.

[ShutingQing]

Generally, I am still not ok with the usage of the term 'slice', since it is against the CAMARA paradigm to hide telco complexity and allow the telco's to decide on the implementation

Hey Thortsen, understand your point. I'll kindly suggest not to discuss the term slice under each PR. Refer to
#12

[tlohmar]

I am wondering, whether we need to differentiate between B2B2X and B2B2B2X from the API design perspective.

[tlohmar]

I suggest to split the "Operators / Aggregator" box into two cases:
(1) Operator <-< Enterprise Customer: Is this a B2B
(2) Operator <-> Aggregator <-> Enterprise Customer: This is a B2B2X case

[tlohmar]

Also here, the Operator / Aggregator Box should be splitted

(1) Operator <-> OTT <-> toC Customer: Is this a B2B2X , here B2B2C
(2) Operator <-> Aggregator <-> OTT <-> toC Customer: This is a B2B2B2C case

When there is an aggregator, which entity is acting as a broker? OTT or also the aggregator?

[tlohmar]

Also here, the Operator / Aggregator Box should be splitted

(1) Operator <-> OTT <-> toC Customer: Is this a B2B2X , here B2B2C
(2) Operator <-> Aggregator <-> OTT <-> toC Customer: This is a B2B2B2C case

[tlohmar]

I have the impression, that several comments are marked as 'resolved' without doin any changes or comments.

[ShutingQing]

I have the impression, that several comments are marked as 'resolved' without doin any changes or comments.

I have the impression, that several comments are marked as 'resolved' without doin any changes or comments.

Hi Thorsten, there are many comments. Some of them I modified. Some of them that I don't think need changes or maybe didn't get your point, so it stay the same and I leave some comments.

No worry, if you have any suggestions, feel free to review~ I'll handle that. This is still in progress stage. And better give me some suggested modifications. @tlohmar

[ShutingQing]

One suggestions is @tlohmar . May I kindly suggest that, maybe you can split your questions and your review suggestions. : ) That will be easier for me do know which are the questions, and which are modification suggestions. Thanks in advance!

[ShutingQing]

@tlohmar I've listed all your comments here. Hopefully it can be more clear. Please check if there is any not included. I believe some of the questions are originated from “Mode” and “What is OTT/Aggregator" is not aligned. I will leave another comment below. After this is discussed clear, let's modify the left together.

1. Question: toB Is this an abbreviation?
-> : Yes. toB, toC means to business(eg enterprise customer), to customer(individual customer).

2. Comment: What is a NaaS API. Please add a reverence.
-> : Modified. NaaS API means CAMARA NaaS Service API.

3. Comment: Line 16, I suggest to focus on this API, e.g. 'this API allows the booking of a slice / resource with very short lead times'.
-> : Modified.

4. Question and Comment: Line20-23. 'OTT' typically not refers to an actor. What is meant here? Does OTT resolve to Over-The-Top? Is this here an Application Provider or an Application Service Provider, who is the customer (not OTT)?

• -> : OTT not equals to Aggregator. This is mode question. Suggested to discuss together below.

5. Question and Comment: Line28-31. I think, OPG uses the term 'Aggregator'.

• -> : OTT not equals to Aggregator. This is mode question. Suggested to discuss together below.

6. Question and Comment: Line 35-37. what is the relation between the 'Provider" and 'OTT'?
-> : Modified. Provider means Telecom Operator.

7. Question: Line 41-43. The OTT refers here to an aggregator, who then resells the service to Enterprises or Consumers, correct? Is this the B2B2B2C scenario? Operators 2 Aggregator 2 OTT 2 consumer? When correct, this is a scenario with two aggregators involved. I suggest to rename 'OTT' to 'Aggregator#2'

• -> : This is mode question. Suggested to discuss together below.

8. Comment: Line57. Typo.
-> : Modified

9. Question: Line 57-60. At what time is it possible to 'Manage access control'?In my understanding, the resource (a slice or a dedicated network) has at least two states, i.e. RESERVED, ACTIVE. It should be possible to have device access control during both states.
-> : Yes.

10. Comment: Line 60-63. Which API should be used, while the reservation is 'active'? I think, API should not be named 'reserve'. Maybe 'manage'
-> : Yes.

11. Comment: Line 66-68. This can be simplified, since all the three bullets kind of say the same thing: Device Access Management may happen at any point in time while the resource is in revered-state and in active-state.
-> : Modifed.

12. Question: I am wondering about the 'may' in 'Slice Owners may have the right to allow access': What is the use-case, when the Slice Owner has NOT the right to allow access of devices? In which cases can the operator add other devices into the resource?

• -> : Mode question. Discuss below.

[ShutingQing]

For the mode question:

1. OTT and Aggregator: I believe OTT is not Aggregator. OTT is cosumer from Aggregator.

2. For the Mode, as Thorsten suggested, B2B2B2C stands for Telecom Operator, to Aggregator, to toB OTT, to toC Customer. Logically this is correct. But I'm worrying this is to complex. How about sort NaaS Platform together, no matter the NaaS Platform is from Telecom Operator's NaaS Platform Portal, or it's from Aggregator's NaaS Platform Portal. Then the Mode is much clear. B2B2C. Stands for, B(CAMARA NaaS Service API) toB(OTT Enterprise) toC (End User End Customer). Any thoughts?

3. B2C and B2X: For B2X mode, there is only few references. Most of the business modes are expressed in the way of B2B, B2C, or B2D. I noticed @tlohmar your suggestion on changing B2C to B2X. Could you elaborate more on the reason of the suggestion on B2X? I'm guessing, whether you are suggesting to change B2C to B2D(to Developer)?

[tlohmar]

Thanks for the elaboration.

One suggestions is @tlohmar . May I kindly suggest that, maybe you can split your questions and your review suggestions

Hmm, I am making suggestions, e.g. "I suggest to split the "Operators / Aggregator" box into two cases". Still, the figures handle the "with aggregator" and "without aggregator" together.

[tlohmar]

Two suggestions embedded.

[tlohmar]

Two suggestions:
1: Change "Enterprise Developer" to "Enterprise". Background: The Enterprise Developer is only interacting with the Service API during the development process. Once the development is completed, the API invoker functionality gets into production and the Developer is not involved anymore.

2: Create two figures:
Fig (1) is: "Operator NaaS Platform" <-> "Enterprise"
Fig (2) is: "Operator NaaS Platform" <-> "Aggregator NaaS Platform" <-> "Enterprise"

[tlohmar]

This NaaS Portal Box_looks confusing: Does this picture mean, that one NaaS Portal contains both, the operator and the aggregator portal in the same instance?
Does the NaaS Portal always contain both subcomponents (Operator NaaS Portal and Aggregator NaaS Portal) or only one (Operator NaaS Portal or Aggregator NaaS Portal)?
I can make a suggestion, once I understand the intention.

[Bart-Ericsson]

Existing material can be used https://github.com/camaraproject/WorkingGroups/blob/main/Marketing/documentation/MarketingMaterial/CAMARA%20Presentation.pptx
Please see slide 12 and 13

[ShutingQing]

Existing material can be used https://github.com/camaraproject/WorkingGroups/blob/main/Marketing/documentation/MarketingMaterial/CAMARA%20Presentation.pptx Please see slide 12 and 13

Thanks Bart . If every one align on this, i will modify the graph based on this.

[Bart-Ericsson]

Existing material can be used https://github.com/camaraproject/WorkingGroups/blob/main/Marketing/documentation/MarketingMaterial/CAMARA%20Presentation.pptx Please see slide 12 and 13

Thanks Bart . If every one align on this, i will modify the graph based on this.

Yes please, but also consider slide 13. As you can see the Service APIs extend into the operator environment upto the transformation function. The transformation function is outside the scope of Camara and every operator can define this transformation function in their own way to realize the intent of the Service API.

[ShutingQing]

Yes totally agree. TF is out of the scope.

[Masa8106]

I hope this is not too late to comment.

There is text "The business modes of Network Slice Booking can be B2B, B2B2C.", which B2C has removed from.
I am not sure a reason why it has remove so far, however I believe B2C is a possible business mode which should be in scope.
Therefore, I would like to suggest B2C to be reverted.

Regarding figure illustration, I think we can change from "Enterprise" to "toB/toC Customer" in the figure of Mode 1.

What do you think about?

[DanXu-ChinaTelecom]

From my side，this API is for developer, B2C model refers to the end user as developer to use this API, maybe this situation doesn't exist for the time being.

[DanXu-ChinaTelecom]

@ShutingQing Mode 2 and Model 3, I think the toC Customer will pay for app serivice with vip/svip experience supported by network slice from the OTT APPs(not OTT developer), the toC Customer indirectly pay for guaranteed network slice service.

[Masa8106]

@DanXu-ChinaTelecom: Thanks for your clarification. From perspective on how API is used by developers, I can make sense with what you mentioned that B2C model is not needed in this diagram.

@ShutingQing: One suggestion. How about changing "toD OTT Developer" to "toD APP Developer" in Mode 2 and 3 of the diagram, because there is word "APP Developer" in the body text.

[ShutingQing]

@Masa8106 Thanks Masaharu and Dan, good suggestion, let's do that.

[ShutingQing]

@ShutingQing Mode 2 and Model 3, I think the toC Customer will pay for app serivice with vip/svip experience supported by network slice from the OTT APPs(not OTT developer), the toC Customer indirectly pay for guaranteed network slice service.

Yes, that's true. For here it's both correct to use toD or toB to stand for OTT/APP developers. Just to see which one is more accurate or easy to understand. toD is more direct.

[hdamker]

I'm a bit surprised about the business model discussions within this document. The scope of CAMARA is defined as "CAMARA only works on customer-facing northbound APIs." Customer in the sense of the end customer of the API, the term application service provider (ASP) is often used here in the meantime. Business model discussions are subject of the GSMA OGW business work stream, but do not need to be repeated here in CAMARA from my perspective.

It would be good if you focus on how a customer who is consuming the Network Slice Booking API(s) would use it, independent of the type of customer. Within the picture from the CAMARA presentation (btw also part of the ProjectCharter) this are blue lines. How an aggregator (or "OTT" in your picture) will package it in own enriched products/service is out of scope.

I would also recommend to avoid telco specific terms like "OTT", this term does not make sense in a collaborative eco-system.

And on the formal side I suggest that the complete document belongs into supporting documents, the documentation folder is about documentation of the API. Also "Network Slice Booking API Introduction.pptx" need to be moved, within Documentation only markdown is expected, see ProjectStructureAndRoles (with ppt we have no version control and review process)).