Re: [openstack-dev] [api] Request Validation - Stoplight
+1 that's a great way to state it Sam. regards, mike - Original Message - Hi Amit, Keeping in mind this viewpoint is nothing but my own personal view, my recommendation would be to not mandate the use of a particular validation framework, but to instead define what kind of validation clients should expect the server to perform in general. For example, I would expect a service to return an error code and not perform any action if I called Create server but did not include a request body, but the actual manner in which that error is generated within the service does not matter from the client's perspective. This is not to say the API Working Group wouldn't help you evaluate the potential of Stoplight to meet the needs of a service. To the contrary, by clearly defining the expectations of a service's responses to requests, you'll have a great idea of exactly what to look for in your evaluation, and your final decision would be based on objective results. Thank you, Sam Harwell ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Request Validation - Stoplight
Thanks for the clarification Sam. Its good to know where the mission of the API working group starts and stops. During the meetup discussions, my understanding was that the working group would recommend the technologies to use while building apis (e.g. Pecan, validation frameworks, etc) and were in the process of looking into tools such as warlock. Hence the recommendation to add another library into the mix for evaluation, based on advise by other stackers in the community. Your response clarifies that the aim of the API working group is just to recommend on standardizing the interfaces from various API's (which I am looking forward to) and not the libraries used to implement that interface. For stackers who are interested in different validation frameworks to implement validation, I recommend checking out Stoplight. Thanks Amit Gandhi. On 10/20/14, 9:36 AM, Michael McCune mimcc...@redhat.com wrote: +1 that's a great way to state it Sam. regards, mike - Original Message - Hi Amit, Keeping in mind this viewpoint is nothing but my own personal view, my recommendation would be to not mandate the use of a particular validation framework, but to instead define what kind of validation clients should expect the server to perform in general. For example, I would expect a service to return an error code and not perform any action if I called Create server but did not include a request body, but the actual manner in which that error is generated within the service does not matter from the client's perspective. This is not to say the API Working Group wouldn't help you evaluate the potential of Stoplight to meet the needs of a service. To the contrary, by clearly defining the expectations of a service's responses to requests, you'll have a great idea of exactly what to look for in your evaluation, and your final decision would be based on objective results. Thank you, Sam Harwell ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Request Validation - Stoplight
On 10/20/2014 10:26 AM, Amit Gandhi wrote: Thanks for the clarification Sam. Its good to know where the mission of the API working group starts and stops. During the meetup discussions, my understanding was that the working group would recommend the technologies to use while building apis (e.g. Pecan, validation frameworks, etc) and were in the process of looking into tools such as warlock. Sorry, did I miss something? What meetup discussions are you referring to? I'm not aware of any meetings of the API working group so far... Hence the recommendation to add another library into the mix for evaluation, based on advise by other stackers in the community. Your response clarifies that the aim of the API working group is just to recommend on standardizing the interfaces from various API's (which I am looking forward to) and not the libraries used to implement that interface. I don't really think the working group has decided yet what it will be producing, with regards to recommendations and what topics it may provide guidance on. Heck, AFAIK, we still haven't settled on a day of the week and time to hold IRC meetings! ;) For stackers who are interested in different validation frameworks to implement validation, I recommend checking out Stoplight. Just my two cents on this particular topic, I think it's more important to standardize ways in which our public REST APIs expose the payload expectations and response schemas to clients. In other words... we need to focus on methods for API discovery. Once you have standardized resource URI, request payload, and response schema discovery, then any number of validation libraries may be used. Best, -jay ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Request Validation - Stoplight
On 10/20/14, 10:38 AM, Jay Pipes jaypi...@gmail.com wrote: On 10/20/2014 10:26 AM, Amit Gandhi wrote: Thanks for the clarification Sam. Its good to know where the mission of the API working group starts and stops. During the meetup discussions, my understanding was that the working group would recommend the technologies to use while building apis (e.g. Pecan, validation frameworks, etc) and were in the process of looking into tools such as warlock. Sorry, did I miss something? What meetup discussions are you referring to? I'm not aware of any meetings of the API working group so far... Sorry, I was referring to the local Atlanta Openstack Meetup that happened last Thursday (mentioned in my initial email that started this thread). Hence the recommendation to add another library into the mix for evaluation, based on advise by other stackers in the community. Your response clarifies that the aim of the API working group is just to recommend on standardizing the interfaces from various API's (which I am looking forward to) and not the libraries used to implement that interface. I don't really think the working group has decided yet what it will be producing, with regards to recommendations and what topics it may provide guidance on. Heck, AFAIK, we still haven't settled on a day of the week and time to hold IRC meetings! ;) Okay good to know. That probably explains why I¹m hearing different things from different people who probably all have different visions of what the working group is. For stackers who are interested in different validation frameworks to implement validation, I recommend checking out Stoplight. Just my two cents on this particular topic, I think it's more important to standardize ways in which our public REST APIs expose the payload expectations and response schemas to clients. In other words... we need to focus on methods for API discovery. Once you have standardized resource URI, request payload, and response schema discovery, then any number of validation libraries may be used. +1 Best, -jay ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Request Validation - Stoplight
On 20 October 2014 15:38, Jay Pipes jaypi...@gmail.com wrote: On 10/20/2014 10:26 AM, Amit Gandhi wrote: Thanks for the clarification Sam. Its good to know where the mission of the API working group starts and stops. During the meetup discussions, my understanding was that the working group would recommend the technologies to use while building apis (e.g. Pecan, validation frameworks, etc) and were in the process of looking into tools such as warlock. Sorry, did I miss something? What meetup discussions are you referring to? I'm not aware of any meetings of the API working group so far... The original poster was probably referring to conversations held in openstack meetups around the world. Hence the recommendation to add another library into the mix for evaluation, based on advise by other stackers in the community. Your response clarifies that the aim of the API working group is just to recommend on standardizing the interfaces from various API's (which I am looking forward to) and not the libraries used to implement that interface. I don't really think the working group has decided yet what it will be producing, with regards to recommendations and what topics it may provide guidance on. Heck, AFAIK, we still haven't settled on a day of the week and time to hold IRC meetings! ;) Eh... a working group on API standards that can't even achieve consensus on a day of the week! For stackers who are interested in different validation frameworks to implement validation, I recommend checking out Stoplight. Just my two cents on this particular topic, I think it's more important to standardize ways in which our public REST APIs expose the payload expectations and response schemas to clients. In other words... we need to focus on methods for API discovery. Once you have standardized resource URI, request payload, and response schema discovery, then any number of validation libraries may be used. I completely agree with Jay. The mission has not yet been scoped, but my feeling is that technologies and/or frameworks won't be something that will be addressed. My personal opinion is that this group will need to focus on the API seen as the way in which consumers interact with Openstack, try and provide a common experience across Openstack API endpoints, and possibly improve the consumer experience by reducing nonsenses and antipatterns in our API. How this is implemented - and hence which technologies and frameworks should be used - is possibly not really in the scope of this group. Salvatore Best, -jay ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Request Validation - Stoplight
On Mon, 20 Oct 2014 10:38:58 -0400 Jay Pipes jaypi...@gmail.com wrote: For stackers who are interested in different validation frameworks to implement validation, I recommend checking out Stoplight. Just my two cents on this particular topic, I think it's more important to standardize ways in which our public REST APIs expose the payload expectations and response schemas to clients. In other words... we need to focus on methods for API discovery. Once you have standardized resource URI, request payload, and response schema discovery, then any number of validation libraries may be used. I agree standardising our APIs is more important. However there is an advantage to projects using the same libraries where practical. Its easier for developers to move from project to project, fewer dependencies for the project overall and when we do run into problems with libraries there are more people familiar with library. However I don't think we should be mandating specific libraries, but we can make recommendations (good or bad) based on actual experience. This will be especially useful to new projects starting up to benefit from the pain other projects have experienced. Regards, Chris ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Request Validation - Stoplight
Hi Amit, Thanks for picking this topic up, Honestly I don't have a strong opinion about validation libraries. Each project implements based on different web frameworks and the options of validation libraries would be limited from its web framework. For example, Nova implements its own wsgi framework and it is difficult to use pecan/wsme due to its API routing/parameter names. So Nova uses jsonschema for a new API(Nova v2.1 API) because of its flexibility and portability. From quick seeing, stoplight seems flexible and it could cover many cases. That would be nice for me, but I'm not sure that stoplight is the best library because jsonschema is a common way/library and portable. Related to this topic, I'd like to suggest that we have common validation patterns across OpenStack projects. Now each project contains its owns validation patterns for the other project's resource. For example, Nova contains validation patterns for project-id and image-id on the code[1]. Ideally, these validation patterns would be nice to be ported/shared from Keystone and Glance and it is the best to use the same validation patterns between whole OpenStack projects for consistent interfaces. Maybe we can implement these patterns even if using different validation libraries. Thanks Ken Ohmichi --- [1]: https://github.com/openstack/nova/blob/master/nova/api/validation/parameter_types.py#L68 -Original Message- From: Amit Gandhi [mailto:amit.gan...@rackspace.com] Sent: Saturday, October 18, 2014 2:32 AM To: OpenStack Development Mailing List (not for usage questions) Cc: r...@ryanpetrello.com Subject: [openstack-dev] [api] Request Validation - Stoplight Hi API Working Group Last night at the Openstack Meetup in Atlanta, a group of us discussed how request validation is being performed over various projects and how some teams are using pecan wsmi, or warlock, jsonschema etc. Each of these libraries have their own pro’s and con’s. My understanding is that the API working group is in the early stages of looking into these various libraries and will likely provide guidance in the near future on this. I would like to suggest another library to evaluate when deciding this. Some of our teams have started to use a library named “Stoplight”[1][2] in our projects. For example, in the Poppy CDN project, we found it worked around some of the issues we had with warlock such as validating nested json correctly [3]. Stoplight is an input validation framework for python. It can be used to decorate any function (including routes in pecan or falcon) to validate its parameters. Some good examples can be found here [4] on how to use Spotlight. Let us know your thoughts/interest and we would be happy to discuss further on if and how this would be valuable as a library for API request validation in Openstack. Thanks Amit Gandhi Senior Manager ? Rackspace [1] https://pypi.python.org/pypi/stoplight [2] https://github.com/painterjd/stoplight [3] https://github.com/stackforge/poppy/blob/master/poppy/transport/pecan/controllers/v1/services.py#L108 [4] https://github.com/painterjd/stoplight/blob/master/stoplight/tests/test_validation.py#L138 ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Request Validation - Stoplight
- Original Message - However I don't think we should be mandating specific libraries, but we can make recommendations (good or bad) based on actual experience. This will be especially useful to new projects starting up to benefit from the pain other projects have experienced. +1 i think it's also important to ensure that these recommendations live in a place that is easy to find. it would be really nice to have example design recipes that are commonly used across projects, but i'm not sure if that gets too far into dictating or mandating certain usage patterns. regards, mike ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Request Validation - Stoplight
On Tue, Oct 21, 2014 at 12:15 PM, Kenichi Oomichi oomi...@mxs.nes.nec.co.jp wrote: Hi Amit, Thanks for picking this topic up, Honestly I don't have a strong opinion about validation libraries. Each project implements based on different web frameworks and the options of validation libraries would be limited from its web framework. For example, Nova implements its own wsgi framework and it is difficult to use pecan/wsme due to its API routing/parameter names. So Nova uses jsonschema for a new API(Nova v2.1 API) because of its flexibility and portability. From quick seeing, stoplight seems flexible and it could cover many cases. That would be nice for me, but I'm not sure that stoplight is the best library because jsonschema is a common way/library and portable. Related to this topic, I'd like to suggest that we have common validation patterns across OpenStack projects. Now each project contains its owns validation patterns for the other project's resource. For example, Nova contains validation patterns for project-id and image-id on the code[1]. Ideally, these validation patterns would be nice to be ported/shared from Keystone and Glance and it is the best to use the same validation patterns between whole OpenStack projects for consistent interfaces. Maybe we can implement these patterns even if using different validation libraries. This sounds good. Would you mind adding it to the wiki here? https://wiki.openstack.org/wiki/Governance/Proposed/APIGuidelines So we don't lose track of it - we don't have the git/gerrit repository up quite yet. Regards, Chris ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Request Validation - Stoplight
Hi Chris, 2014-10-21 13:41 GMT+09:00 Christopher Yeoh cbky...@gmail.com: On Tue, Oct 21, 2014 at 12:15 PM, Kenichi Oomichi oomi...@mxs.nes.nec.co.jp wrote: Hi Amit, Thanks for picking this topic up, Honestly I don't have a strong opinion about validation libraries. Each project implements based on different web frameworks and the options of validation libraries would be limited from its web framework. For example, Nova implements its own wsgi framework and it is difficult to use pecan/wsme due to its API routing/parameter names. So Nova uses jsonschema for a new API(Nova v2.1 API) because of its flexibility and portability. From quick seeing, stoplight seems flexible and it could cover many cases. That would be nice for me, but I'm not sure that stoplight is the best library because jsonschema is a common way/library and portable. Related to this topic, I'd like to suggest that we have common validation patterns across OpenStack projects. Now each project contains its owns validation patterns for the other project's resource. For example, Nova contains validation patterns for project-id and image-id on the code[1]. Ideally, these validation patterns would be nice to be ported/shared from Keystone and Glance and it is the best to use the same validation patterns between whole OpenStack projects for consistent interfaces. Maybe we can implement these patterns even if using different validation libraries. This sounds good. Would you mind adding it to the wiki here? https://wiki.openstack.org/wiki/Governance/Proposed/APIGuidelines So we don't lose track of it - we don't have the git/gerrit repository up quite yet. I see, I wrote it as POST/PUT body validation on the wiki. Thanks Ken Ohmichi ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Request Validation - Stoplight
Hi Amit, Keeping in mind this viewpoint is nothing but my own personal view, my recommendation would be to not mandate the use of a particular validation framework, but to instead define what kind of validation clients should expect the server to perform in general. For example, I would expect a service to return an error code and not perform any action if I called Create server but did not include a request body, but the actual manner in which that error is generated within the service does not matter from the client's perspective. This is not to say the API Working Group wouldn't help you evaluate the potential of Stoplight to meet the needs of a service. To the contrary, by clearly defining the expectations of a service's responses to requests, you'll have a great idea of exactly what to look for in your evaluation, and your final decision would be based on objective results. Thank you, Sam Harwell From: Amit Gandhi [mailto:amit.gan...@rackspace.com] Sent: Friday, October 17, 2014 12:32 PM To: OpenStack Development Mailing List (not for usage questions) Cc: r...@ryanpetrello.com Subject: [openstack-dev] [api] Request Validation - Stoplight Hi API Working Group Last night at the Openstack Meetup in Atlanta, a group of us discussed how request validation is being performed over various projects and how some teams are using pecan wsmi, or warlock, jsonschema etc. Each of these libraries have their own pro's and con's. My understanding is that the API working group is in the early stages of looking into these various libraries and will likely provide guidance in the near future on this. I would like to suggest another library to evaluate when deciding this. Some of our teams have started to use a library named Stoplight[1][2] in our projects. For example, in the Poppy CDN project, we found it worked around some of the issues we had with warlock such as validating nested json correctly [3]. Stoplight is an input validation framework for python. It can be used to decorate any function (including routes in pecan or falcon) to validate its parameters. Some good examples can be found here [4] on how to use Spotlight. Let us know your thoughts/interest and we would be happy to discuss further on if and how this would be valuable as a library for API request validation in Openstack. Thanks Amit Gandhi Senior Manager - Rackspace [1] https://pypi.python.org/pypi/stoplight [2] https://github.com/painterjd/stoplight [3] https://github.com/stackforge/poppy/blob/master/poppy/transport/pecan/controllers/v1/services.py#L108 [4] https://github.com/painterjd/stoplight/blob/master/stoplight/tests/test_validation.py#L138 ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
