Hi Thinh, Are you capturing all IFA and SOL specs?
Thanks, Alex From: [email protected] [mailto:[email protected]] On Behalf Of Nguyenphu, Thinh (Nokia - US/Irving) Sent: Wednesday, July 19, 2017 3:25 PM To: Stephen Terrill <[email protected]>; [email protected] Cc: [email protected]; [email protected]; [email protected]; [email protected]; [email protected]; [email protected] 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, 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: [email protected]<mailto:[email protected]> [mailto:[email protected]] On Behalf Of Stephen Terrill Sent: Wednesday, July 19, 2017 7:37 AM To: [email protected]<mailto:[email protected]> Cc: [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]> 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: [email protected]<mailto:[email protected]> [mailto:[email protected]] Sent: 19 July 2017 10:48 To: Stephen Terrill <[email protected]<mailto:[email protected]>> Cc: [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]> 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: <[email protected]<mailto:[email protected]>>; To: zhaohuabing10201488; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>;FuGuangRong10144542; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; 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: [email protected]<mailto:[email protected]> [mailto:[email protected]] Sent: 11 July 2017 05:10 To: [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; Stephen Terrill <[email protected]<mailto:[email protected]>>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]> Cc: [email protected]<mailto:[email protected]> 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: <[email protected]<mailto:[email protected]>>; To: <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>;zhaohuabing10201488; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>;FuGuangRong10144542; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; <[email protected]<mailto:[email protected]>>; CC: <[email protected]<mailto:[email protected]>>; 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: <[email protected]<mailto:[email protected]>> 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: <[email protected]<mailto:[email protected]>>; To: zhaohuabing10201488; <[email protected]<mailto:[email protected]>>; 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: <[email protected]<mailto:[email protected]>> on behalf of "[email protected]<mailto:[email protected]>" <[email protected]<mailto:[email protected]>> Date: Thursday, June 22, 2017 at 7:14 AM To: "[email protected]<mailto:[email protected]>" <[email protected]<mailto:[email protected]>> 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<https://urldefense.proofpoint.com/v2/url?u=https-3A__wiki.onap.org_display_DW_RESTful-2BAPI-2BDesign-2BBest-2BPractices&d=DwMGaQ&c=LFYZ-o9_HUMeMTSQicvjIg&r=jwTiArcEj6aUX0HjV0M3dT12gUtk7rC07xpgpVZkS_4&m=0YNbxUNtVvCKpTNvgW3_BNoCLCj_MRe742y6dx4OBmU&s=_ZowHTJvm1zMQejvK18VIV9y5yd9QptiXikmoUw-5P4&e=> 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 [email protected]<mailto:[email protected]> https://lists.onap.org/mailman/listinfo/onap-discuss
_______________________________________________ ONAP-TSC mailing list [email protected] https://lists.onap.org/mailman/listinfo/onap-tsc
