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]>
To: <[email protected]> <[email protected]>
<[email protected]> <[email protected]> <[email protected]>
<[email protected]>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]>FuGuangRong10144542
<[email protected]> <[email protected]> <[email protected]>
<[email protected]> <[email protected]> <[email protected]>
<[email protected]> <[email protected]>
CC: <[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]>
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]>
To: zhaohuabing10201488 <[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]> on behalf of
"[email protected]" <[email protected]>
Date: Thursday, June 22, 2017 at 7:14 AM
To: "[email protected]" <[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
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]
https://lists.onap.org/mailman/listinfo/onap-discuss
_______________________________________________
ONAP-TSC mailing list
[email protected]
https://lists.onap.org/mailman/listinfo/onap-tsc
