Hi Huabing, Thanks for looking into details of the swagger-sdk project in Open-O and we are in the same page.
Like to add some more specific points: 1. build time part of swagger-sdk is done in Open-O->oparent project and ONAP already leveraged this oparent project from Open-O. So we could also leverage swagger-sdk part in oparent project from Open-O. 2. for run-time part of swagger-sdk, as you suggested it could be created as sub-project under MSB project. And thanks for suggesting different approach for “API committee”, which help to look at from different perspective. Regards Kanagaraj M *************************************************************************************** 本邮件及其附件含有华为公司的保密信息，仅限于发送给上面地址中列出的个人或群组。禁止任何其他人以任何形式使用（包括但不限于全部或部分地泄露、复制、或散发）本邮件中的信息。如果您错收了本邮件，请您立即电话或邮件通知发件人并删除本邮件！************************************************************************************** *************************************************************************************** This e-mail and its attachments contain confidential information from HUAWEI, which is intended only for the person or entity whose address is listed above. Any use of the information contained herein in any way (including, but not limited to, total or partial disclosure, reproduction, or dissemination) by persons other than the intended recipient(s) is prohibited. If you receive this e-mail in error, please notify the sender by phone or email immediately and delete it! *************************************************************************************** From: [email protected] [mailto:[email protected]] Sent: 12 July 2017 09:07 To: Kanagaraj Manickam Cc: [email protected]; [email protected]; [email protected]; [email protected]; [email protected]; [email protected]; [email protected]; Yunxia Chen; [email protected]; [email protected]; [email protected]; [email protected]; [email protected]; [email protected]; denghui (L); [email protected]; [email protected]; [email protected]; [email protected]; Gildas Lanilis; [email protected]; [email protected]; [email protected]; [email protected]; [email protected]; [email protected]; [email protected]; [email protected]; [email protected]; Seshu m; [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 Kanagaraj, Thanks for your feedback and the great suggestion. Sorry for the late response, I cost me some time to read the wiki and go through the codes of the swagger-sdk, I'd like to make sure I understand what's the scope of the SDK before my response. I think the tool what you're proposing would be very helpful for ONAP. Below is what I learned from the page, please correct me if I was wrong. 1. The build-time tool would go to integration team, so we could work with them to integrate build-time tool to ONAP CI/CD system. 2. The run-time tool is a shared lib for Restful APIs and Swagger which could be leveraged by other projects. It might make sense to put it under MSB project as a sub repo. Regarding the API committee, In my opinion, It's better we have some kind of "organization" to govern this task and coordinate the projects to make consistency at API level. I am just not sure what kind of "organization" it should be? We have a few options here: 1. An API subcommittee as you mentioned 2. A "work group" under Architecture subcommittee 3. A "work group" under documentation project I think we could wait for more feedback from the community and ask direction from TSC to figure it out. We can discuss at the next weekly PTLs meeting with the RESTful API Design Specification. Thanks, Huabing Original Mail Sender: <[email protected]>; To: zhaohuabing10201488; <[email protected]>; <[email protected]>; <[email protected]>; <[email protected]>; <[email protected]>; <[email protected]>; <[email protected]>; <[email protected]>; <[email protected]>; <[email protected]>; <[email protected]>; <[email protected]>; <[email protected]>; <[email protected]>; <[email protected]>; <[email protected]>; <[email protected]>; <[email protected]>; <[email protected]>; <[email protected]>; <[email protected]>; <[email protected]>; <[email protected]>; <[email protected]>;fuguangrong10144542; <[email protected]>; <[email protected]>; <[email protected]>; <[email protected]>; <[email protected]>; CC: <[email protected]>; Date: 2017/07/11 11:51 Subject: RE: Solicit PTL feedback for ONAP RESTful API Design Specification//Fw:[onap-tsc][ptls] proposed topic for the next week's PTL meeting Dear Huabing, Thanks for bring this topic across the community and its very helpful to bring the consistency in REST API in terms of URI pattern, response formats, versioning, etc. It also helps to make the integration points of ONAP smoother whether its internal/external. Btw, I would like to bring couple of things related to this topic here, let me know your feedback: 1. We tried to solve the similar issues in Open-O, by the project name called swagger-sdk. During the build time, it helps to generate swagger.json and java client sdk and during the run-time, it helps to provide the swagger.json at the given URI. More details are available in the wiki. https://wiki.open-o.org/display/CLIEN/Swagger+SDK+for+Open-O It could be leveraged into ONAP. 2. Should we form an API committee to govern this task, similar to other communities like OpenStack. Thanks. Regards Kanagaraj M *************************************************************************************** 本邮件及其附件含有华为公司的保密信息，仅限于发送给上面地址中列出的个人或群组。禁止任何其他人以任何形式使用（包括但不限于全部或部分地泄露、复制、或散发）本邮件中的信息。如果您错收了本邮件，请您立即电话或邮件通知发件人并删除本邮件！************************************************************************************** *************************************************************************************** This e-mail and its attachments contain confidential information from HUAWEI, which is intended only for the person or entity whose address is listed above. Any use of the information contained herein in any way (including, but not limited to, total or partial disclosure, reproduction, or dissemination) by persons other than the intended recipient(s) is prohibited. If you receive this e-mail in error, please notify the sender by phone or email immediately and delete it! *************************************************************************************** From: [email protected] [mailto:[email protected]] Sent: Tuesday, July 11, 2017 8:40 AM To: [email protected]; [email protected]; [email protected]; Kanagaraj Manickam; [email protected]; [email protected]; [email protected]; [email protected]; Yunxia Chen; [email protected]; [email protected]; [email protected]; [email protected]; [email protected]; [email protected]; denghui (L); [email protected]; [email protected]; [email protected]; [email protected]; Gildas Lanilis; [email protected]; [email protected]; [email protected]; [email protected]; [email protected]; [email protected]; [email protected]; [email protected]; [email protected]; Seshu m Cc: [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
