Re: [onap-tsc] Solicit PTL feedback for ONAP RESTful API DesignSpecification//Fw:[ptls] proposed topic for the next week's PTL meeting

[zhao.huabing]

Hi Thinh,


Thanks for reaching out for help.


I have successfully downloaded this document 
https://docbox.etsi.org/ISG/NFV/Open/Drafts/SOL005_Os-Ma-nfvo_APIs 



We should align the ONAP specification with "4 General Aspects" clause, 
Currently, I'm analysing it and will update the ONAP specification accordingly 
if any misalignment found. I would appreciate if anyone from ONAP community 
could review and send me feedback.






My expectation is that we could figure out the minimum but most important set 
of rules to guide the REST API design of ONAP projects so the client and 
developers can have consistent and easy to use API for ONAP.  The date should 
be at least two weeks before M3 API freeze Aug. 24.






We may also keep in mind that ONAP specification is not fixed after its first 
release and will be open for contribution and updating along with the 
development of ONAP platform, so after the official release of SOL, we still 
have chances to go back to improve this specification. 




What do you think?




Thanks,

Huabing



Original Mail



Sender:  <thinh.nguyen...@nokia.com>
To:  <stephen.terr...@ericsson.com>zhaohuabing10201488
CC:  <rk5...@att.com> <ah0...@intl.att.com> <gg2...@att.com> <es4...@att.com> 
<sw3...@att.com> <onap-tsc@lists.onap.org>
Date: 2017/07/20 06:25
Subject: RE: [onap-tsc] Solicit PTL feedback for ONAP RESTful API 
DesignSpecification//Fw:[ptls] proposed topic for the next week's PTL meeting







Hi Huabing,


 


I am in the process of getting ETSI NFV to make the document public  available 
or share with ONAP projects, and updating the document.  Do you have specific 
timeline on ONAP RESTful API Design Specification?


 


Regards,


Thinh


 



From: onap-tsc-boun...@lists.onap.org [mailto:onap-tsc-boun...@lists.onap.org] 
On Behalf Of Stephen Terrill
 Sent: Wednesday, July 19, 2017 7:37 AM
 To: zhao.huab...@zte.com.cn
 Cc: rk5...@att.com ah0...@intl.att.com gg2...@att.com es4...@att.com 
sw3...@att.com onap-tsc@lists.onap.org
 Subject: Re: [onap-tsc] Solicit PTL feedback for ONAP RESTful API Design 
Specification//Fw:[ptls] proposed topic for the next week's PTL meeting




 

Hi Huabing,

Thanks for considering my input, and I see that you are also getting the 
documents.  Let me know if that is not successful.

Another question was brought to my attention regarding the order – should it be 
/service/API instead of /API/Service ?

Best Regards,

Steve

 

 


 


 


From: zhao.huab...@zte.com.cn [mailto:zhao.huab...@zte.com.cn] 
 Sent: 19 July 2017 10:48
 To: Stephen Terrill <stephen.terr...@ericsson.com>
 Cc: gg2...@att.com ml6...@intl.att.com sw3...@att.com 
kanagaraj.manic...@huawei.com gn4...@intl.att.com lxin...@vmware.com 
denglin...@chinamobile.com jf2...@att.com helen.c...@huawei.com 
ah0...@intl.att.com david.sauvag...@bell.ca am8...@att.com 
talas...@research.att.com dtimo...@att.com rx1...@att.com denghu...@huawei.com 
wangchen...@chinamobile.com shen...@chinamobile.com rk5...@att.com 
pr...@linuxfoundation.org gildas.lani...@huawei.com denghu...@hotmail.com 
es4...@att.com cc...@linuxfoundation.org fu.guangr...@zte.com.cn 
pdrag...@research.att.com sa...@research.att.com l...@research.att.com 
mp...@amdocs.com seshu.kuma...@huawei.com onap-tsc@lists.onap.org
 Subject: Re:RE: Solicit PTL feedback for ONAP RESTful API Design 
Specification//Fw:[onap-tsc][ptls] proposed topic for the next week's PTL 
meeting


 

Hi Stephen,

Thanks for your thoughtful feedback. 

 

Unfortunately, I don't have access to the SOL draft, But I think we definitely 
should avoid potential misalignment with ETSI. If anyone who involved in ETSI 
SOL could help review this, I will very appreciate it.

 

The ONAP RESTful API Design Specification can start with some fundamental 
principles like the URI construct and versioning and it's open for discussion 
and will evolve along with ONAP development, if there is anything is not 
consistent with ETSI SOL, we  should change it.

 

Below is the response specificly regrading your comments

E.g. this proposes hyphons “-“ where ETSI propose underscore “_”

Huabing: My personal opinion is that “-” may be more reasonable, I would be 
great if we know the reasoning behind ETSI SOL, However, to avoid potential 
misalignment with ETSI, I marked this item as TBD.

 

For security reasons, should we use HTTPS instead of HTTP.

Huabing: I added this item to the specification.

 

Also, on the theme of the token, we would probably needs some explanation 
around the handling of the token – i.e. who generates it, how is it validated 
etc.

Huabing: this item is a general rule rather than implementation description. 
The token should be generated and validated by ONAP auth component such as AAF.

 

In versioning, is the compatibility for minor revisions only? (i.e. major 
revisions may not be or?)

Huabing:  It's covered.

Major version: The version used in the URI and denotes breaking changes to the 
API. Internally, a new major version implies creating a new API and the version 
number is used to route to the correct  implementation.

Minor and Patch versions: These are transparent to the client and used 
internally for backward-compatible updates. They should be reflected in the 
swagger files to inform clients about a new functionality  or a bug fix. 

 

Regarding versioning, we should describe the behavior regarding version 
negotiation/discovery, i.e. if the client supports x.1.2 and the server 
supports x.1.1 should the client fallback  to x.1.1 or is it assumed that the 
server politely ignores what it  doesn’t understand.

Huabing: It's covered as as start point, it's an important capability but we 
may not have time to implement it at Amsterdam release.

Version discovery (Optional)


Need to be discussed: Should ONAP adopt a version discovery mechanism like 
OpenStack?  :https://wiki.openstack.org/wiki/VersionDiscovery


 

What is the recommendation if the “verb” cannot be mapped granularly enough to 
Post/get/put/delete?  (e.g. “tell bailey to come” “tell bailey to sit” “Clean 
bailey”, “tell bailey to bark”, … etc.

Huabing: It's not covered now, it's a start point and can evolve along with 
ONAP development. 

 

Thanks,

Huabing

 


Original Mail



Sender:  <stephen.terr...@ericsson.com>



To: zhaohuabing10201488 <gg2...@att.com> <ml6...@intl.att.com>  
<sw3...@att.com> <kanagaraj.manic...@huawei.com> <gn4...@intl.att.com> 
<lxin...@vmware.com>  <denglin...@chinamobile.com> <jf2...@att.com> 
<helen.c...@huawei.com> <ah0...@intl.att.com>  <david.sauvag...@bell.ca> 
<am8...@att.com> <talas...@research.att.com> <dtimo...@att.com>  
<rx1...@att.com> <denghu...@huawei.com> <wangchen...@chinamobile.com> 
<shen...@chinamobile.com>  <rk5...@att.com> <pr...@linuxfoundation.org> 
<gildas.lani...@huawei.com> <denghu...@hotmail.com>  <es4...@att.com> 
<cc...@linuxfoundation.org>FuGuangRong10144542 <pdrag...@research.att.com> 
<sa...@research.att.com>  <l...@research.att.com> <mp...@amdocs.com> 
<seshu.kuma...@huawei.com> <onap-tsc@lists.onap.org>



Date: 2017/07/19 01:39



Subject: RE: Solicit PTL feedback for ONAP RESTful API Design 
Specification//Fw:[onap-tsc][ptls] proposed topic for the next week's PTL 
meeting




 


Hi Huabing,


 


Thank-you for bringing this topic up for discussion and proposal. 


 


I have some input for you to consider:


 

It has been brought to my attention that similar needs have also being raised 
in other communities, and one such being the ETSI specifications where this has 
been documented in NFVSOL  00050.   It could make sense to avoid unnecessary 
misalignment where possible 
(https://docbox.etsi.org/ISG/NFV/SOL/05-CONTRIBUTIONS/2017/NFVSOL(17)000050r3_SOL_REST_API_convention_collection_living_document.zip
   (if you have access to ETSI,  or hopefully it can be made open), also some 
patterns are described in SOL3 which are not represented in the conventions 
document yet 
(https://docbox.etsi.org/ISG/NFV/SOL/05-CONTRIBUTIONS/2017/NFVSOL(17)000050r3_SOL_REST_API_convention_collection_living_document.zip

https://docbox.etsi.org/ISG/NFV/Open/Drafts/SOL003_Or-Vnfm_protocols/NFV-SOL003v0100.zip
   )

E.g. this proposes hyphons “-“ where ETSI propose underscore “_”

Others ..

(Perhaps there could be help from the stds coordinator appointed for ETSI-NFV 
to help you here???)

For security reasons, should we use HTTPS instead of HTTP.

Also, on the theme of the token, we would probably needs some explanation 
around the handling of the token – i.e. who generates it, how is it validated 
etc.

In versioning, is the compatibility for minor revisions only? (i.e. major 
revisions may not be or?)

Regarding versioning, we should describe the behavior regarding version 
negotiation/discovery, i.e. if the client supports x.1.2 and the server 
supports x.1.1 should the client fallback  to  x.1.1 or is it assumed that the 
server politely ignores what it doesn’t understand.

What is the recommendation if the “verb” cannot be mapped granularly enough to 
Post/get/put/delete?  (e.g. “tell bailey to come” “tell bailey to sit” “Clean 
bailey”, “tell bailey to bark”, …  etc.


 


BR,


 


Steve


 


From: zhao.huab...@zte.com.cn [mailto:zhao.huab...@zte.com.cn] 
 Sent: 11 July 2017 05:10
 To: gg2...@att.com ml6...@intl.att.com sw3...@att.com 
kanagaraj.manic...@huawei.com gn4...@intl.att.com lxin...@vmware.com 
denglin...@chinamobile.com jf2...@att.com helen.c...@huawei.com 
ah0...@intl.att.com david.sauvag...@bell.ca am8...@att.com  
talas...@research.att.com dtimo...@att.com rx1...@att.com denghu...@huawei.com 
wangchen...@chinamobile.com shen...@chinamobile.com rk5...@att.com 
pr...@linuxfoundation.org gildas.lani...@huawei.com denghu...@hotmail.com 
Stephen Terrill <stephen.terr...@ericsson.com>  es4...@att.com 
cc...@linuxfoundation.org fu.guangr...@zte.com.cn pdrag...@research.att.com 
sa...@research.att.com l...@research.att.com mp...@amdocs.com 
seshu.kuma...@huawei.com
 Cc: onap-tsc@lists.onap.org
 Subject: Solicit PTL feedback for ONAP RESTful API Design Specification 
//Fw:[onap-tsc][ptls] proposed topic for the next week's PTL meeting


 

Hi Gregory and PTLs,

 

At the this week's PTL meeting, I get the action item to contact documentation 
team and PTLs to continues the RESTFul API Design discussion.  
http://ircbot.wl.linuxfoundation.org/meetings/onap-meeting/2017/onap-meeting.2017-07-10-13.22.html

 

The reasoning behind this:

API is very important because it's hard to make significant changes to your API 
once it's released, so we want to get as much right as possible at first. 
Currently, most of the projects have already passed their M1 review, the 
Release Planning. And developers   start to write codes.I went through some of 
the existing API documents of a bunch of projects, it seems that there's no 
consistent way for Restful API design and some of the API definition are not 
very appropriate.  

Because it's a cross-project issue, I proposed this topic at this week's PTL 
meeting,  I'd like to suggest that we figure out a unified approach across ONAP 
projects for the Restful API design before we jump into the coding work. 


 

I came up with a draft as the start point for discussion on this wiki page: 
https://wiki.onap.org/display/DW/RESTful+API+Design+Specification+for+ONAP  
.These items in this pages are based on some best practices in the industry, 
such as the URL, resource hierarchy, the versioning, the use of HTTP method, 
API documentation Specification,   etc. 

 

Please discuss the specification within your team. If anything needs to be 
modified or added, just send feedback here by mail or comment on the wiki page. 
I hope we could get a revised and improved version ready for next week's PTL 
meeting.

 

Thank you for your attention to this matter.

Huabing

 

 


Original Mail



Sender:  <zhaohuab...@gmail.com>



To:  <onap-tsc@lists.onap.org> <pr...@linuxfoundation.org>   
<kp...@linuxfoundation.org> <wangchen...@chinamobile.com> <dtimo...@att.com>  
<helen.c...@huawei.com>zhaohuabing10201488  <denglin...@chinamobile.com> 
<pdrag...@research.att.com>  <denghu...@hotmail.com> 
<talas...@research.att.com>  <rk5...@att.com> <seshu.kuma...@huawei.com>  
<am8...@att.com> <cc...@linuxfoundation.org>  <lxin...@vmware.com> 
<jf2...@att.com>  <stephen.terr...@ericsson.com> <ml6...@intl.att.com>  
<mp...@amdocs.com> <sa...@research.att.com>  <l...@research.att.com> 
<gg2...@att.com> <kanagaraj.manic...@huawei.com>  
<gn4...@intl.att.com>FuGuangRong10144542  <denghu...@huawei.com> 
<david.sauvag...@bell.ca> <sw3...@att.com>  <rx1...@att.com>  
<shen...@chinamobile.com> <ah0...@intl.att.com> <gildas.lani...@huawei.com>   
<es4...@att.com>



CC:  <ma...@research.att.com>



Date: 2017/07/07 15:02



Subject: [onap-tsc][ptls] proposed topic for the next week's PTL meeting




 


Dear PTLs, 


 


Maybe we could discuss this topic at the next week's PTL meeting. It's 
important and covers almost all the projects which will produce APIs.



 


https://wiki.onap.org/display/DW/RESTful+API+Design+Specification+for+ONAP 



 


Thanks,



Huabing


---------- Forwarded message ---------
Cc:  <onap-disc...@lists.onap.org>



 

Hi  Pam,

After taking a look at the other best practices on this page. I realized that 
this is more like a specification than best practices because we'd like to 
enforce them to all the ONAP components. I moved this page to 
https://wiki.onap.org/display/DW/RESTful+API+Design+Specification+for+ONAP


 

Agree that some of the projects may not redesign the existing API for 
back-compatible reason, We can maintain the old version while designing the new 
version in parallel. It's possible that both the old and new version can be 
provided to the ONAP clients.

 

Thanks,

Huabing


Original Mail



Sender:  <pdrag...@research.att.com>



To: zhaohuabing10201488 <onap-disc...@lists.onap.org>



Date: 2017/06/22 20:09



Subject: Re: [onap-discuss] RESTful API Design Best Practices for 
ONAPMicroservices










 


Huabing,


 


Thanks, I agree and feel this is very valuable. There is no formal best 
practices for RESTful API, albeit a few websites that do a fairly good job at 
making suggestions.


 


I think this detailed information should probably be in the section located 
here:


 


https://wiki.onap.org/display/DW/Developer+Best+Practices


 


Gildas has been including such details as part of his presentations, and its 
part of the checklist template.


 


We would perhaps also need to be aware for R1 that some projects may not be 
able to re-design quite yet. They may have to support their current API version 
until an appropriate   time to  deprecate it in lieu of new API conforming to 
standards.


 


Thanks,


 


Pam


 


 



From: <onap-discuss-boun...@lists.onap.org> on behalf of 
"zhao.huab...@zte.com.cn" <zhao.huab...@zte.com.cn>
 Date: Thursday, June 22, 2017 at 7:14 AM
 To: "onap-disc...@lists.onap.org" <onap-disc...@lists.onap.org>
 Subject: [onap-discuss] RESTful API Design Best Practices for ONAP 
Microservices



 

Dear ONAPer,

Most of the projects have already been approved in Beijing meeting or will be 
approved in this week's TSC meeting,  we're starting the development phase of 
release 1 right now. I went through the API documents of a bunch of existing 
projects, it seems to    me that there's no consistent approach for Restful API 
design and some of the APIs are not very appropriate.  So I‘d like to suggest 
that we could figure out a unified approach across ONAP projects for the 
Restful API design before jumping into the coding    job. 

I have worked out a draft as the start point for discussion on this wiki page : 
https://wiki.onap.org/display/DW/RESTful+API+Design+Best+Practices 

I hope we could discuss in the community and reach consensus in one or two 
weeks. Then I'd like to propose to TSC using it as a guideline for all the 
projects.

 

What do you think about it?  Please feel free to share your idea in the 
comments of the wiki page so we can improve this draft quickly.

 

Thanks and Regards,

Huabing

 

 

 

 




 







_______________________________________________
onap-discuss mailing list
 onap-disc...@lists.onap.org
 https://lists.onap.org/mailman/listinfo/onap-discuss
_______________________________________________
ONAP-TSC mailing list
ONAP-TSC@lists.onap.org
https://lists.onap.org/mailman/listinfo/onap-tsc