16:00:45 <etoews> #startmeeting api wg
16:00:45 <openstack> Meeting started Thu Aug  4 16:00:45 2016 UTC and is due to finish in 60 minutes.  The chair is etoews. Information about MeetBot at http://wiki.debian.org/MeetBot.
16:00:46 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
16:00:49 <openstack> The meeting name has been set to 'api_wg'
16:00:56 <etoews> #chair cdent elmiko etoews
16:00:56 <openstack> Warning: Nick not in channel: cdent
16:00:57 <openstack> Warning: Nick not in channel: elmiko
16:00:58 <openstack> Current chairs: cdent elmiko etoews
16:01:19 <mlavalle> they left you alone etoews ;-)
16:01:21 <jschwarz> thanks guys
16:01:28 <etoews> mlavalle: apparently so :)
16:01:45 <mlavalle> if you feel lonely, ping me ;-)
16:02:06 <etoews> :)
16:03:56 <dramakri> etoews: hi
16:04:44 <etoews> dramakri: hello!
16:05:43 <dramakri> etoews: will we be discussing - APIs for exposing resource capabilities?
16:06:30 <etoews> dramakri: unfortunately we seem to be a bit understaffed at the moment. the other 2 usual members of the api working group weren't able to make it today.
16:06:41 <etoews> would you still like to discuss it?
16:06:46 <elmiko> o/
16:07:04 <etoews> hello elmiko!
16:07:18 <elmiko> hey, sorry bout that
16:07:30 <elmiko> lost track of time
16:07:37 <etoews> np. well let's dive in and see if we can make any progress.
16:07:40 <etoews> #topic APIs for exposing resource capabilities
16:07:47 <etoews> #link https://review.openstack.org/#/c/306930/
16:07:53 <etoews> #link https://review.openstack.org/#/c/350310/
16:08:15 <etoews> dramakri: care to provide some context? what are you hoping to get out of this discussion?
16:08:37 <dramakri> etoews: sure
16:09:19 <dramakri> I propose defining a capability API for every resource in a REST API where it makes sense and is needed.
16:09:25 <dramakri> this was started for Cinder.
16:10:02 <dramakri> In the context of Cinder, we would have a capability API at the root resource level (GET /v3.x/{tenant_id}/capabilities) that would return, e.g., [“volume-backup", “other-capability”]
16:10:23 <dramakri> Cinder cores suggested that this might be a generic enough problem with other OpenStack services as well
16:10:49 <dramakri> so I am wondering if there are any other projects currently working on capabilities - lets say nova
16:11:03 <etoews> heh. that was my question too.
16:11:09 <elmiko> could you define "capabilities" a little more?
16:13:06 <dramakri> capabilities are the features supported by a cinder service or a lower level resource like volume_types
16:13:28 <elmiko> are these o/s level capabilities then?
16:13:57 <etoews> as a wild swing at seeing what other services support things called "capability or capabilities" i did this search https://github.com/search?l=&q=org%3Aopenstack+capability+OR+capabilities&ref=advsearch&type=Code&utf8=%E2%9C%93
16:14:15 <dramakri> "volume-backup" would be an example for service-level or root resource.
16:14:28 <etoews> it's certainly a popular term. ;)
16:14:33 <dramakri> etoews: looking at your link
16:14:52 <elmiko> heh, that's why i'm curious. is this just some sort of open-ended metadata or is there something behind the term capabilities?
16:15:04 <etoews> hard to say if everything in those results maps to the concept you're describing though
16:15:10 <elmiko> like, i think kernel capabilities when i hear that as some sort of o/s level thing
16:16:09 <dramakri> "capability" is a functionality that may or may not be supported. So, it becomes important to have a way to know whether it is suppoted
16:16:26 <dramakri> For example: volume backup. Some Cinder services support, some dont.
16:16:47 <elmiko> got it
16:16:50 <dramakri> If Horizon could knew when it is supported, it can enable the "Create Volume Backup" button
16:17:59 <dramakri> In Cinder, existing APIs to epose capabilities don't follow any pattern
16:18:12 <dramakri> One sticks it inside the "extra specs" field of a propery bag
16:18:24 <dramakri> Another defines an API, and so on
16:18:39 <etoews> yuck
16:18:48 <dramakri> The spec seeks to regularize it for Cinder and hopefully for other OpenStack projects too
16:19:15 <dramakri> The key concept is "one capability API per resource, where it makes sense"
16:19:30 <elmiko> hmm, sounds a lot like metadata to me. i'm having a hard time visualizing how we would standardize the capabilities themselves
16:19:37 <etoews> even better would be...if a capability isn't supported, it offers a description of *why* it isn't support that is digestible by an end user.
16:20:22 <elmiko> etoews++ great suggestion
16:21:04 <dramakri> The list of capabilities is open ended. We do not know the list of capabilities that are not supported
16:21:06 <etoews> elmiko: it sounds to me like what they basically have now is unstructured metadata (in extra specs) and are looking to structure that into something called capabilities
16:21:26 <etoews> dramakri: is that ^ a fair take on it?
16:21:54 <dramakri> extra specs is just one way Cinder uses. But, yes, your statements is true in general
16:22:12 <elmiko> yeah, i was just thinking from the pattern it sounds like something that could use the mechanics of the metadata guideline, perhaps...
16:22:45 <elmiko> albeit with some sort of capabilities specific endpoint, or similar, for each resource
16:23:28 <etoews> or metadata reserved for use by capabilities
16:23:31 <dramakri> elmiko: do you have a link for the "metadata guideline"?
16:23:57 <elmiko> 1sec
16:24:27 <elmiko> dramakri: http://specs.openstack.org/openstack/api-wg/guidelines/metadata.html
16:24:57 <elmiko> i'm guessing you would ignore the updating and creating parts (which would be handled by the server)
16:27:13 <dramakri> On a quick glance, it seems similar
16:30:10 <dramakri> Has the metadata guideline been adopted by all OpenStack projects?
16:30:53 <elmiko> well, it doesn't quite work like that. but i've seen more than one project adopt it
16:31:27 <etoews> it's the way forward for any project doing a metadata api
16:31:39 <etoews> (or changes to a metadata api)
16:31:51 <elmiko> ++
16:32:31 <dramakri> Does it mean that we should use the term "capabilities" for Cinder?
16:33:14 <dramakri> *we should NOT use the term ...
16:34:19 <elmiko> imo, it's fine if we want to describe a general use for the metadata stuff as capabilities. i feel this is more a process thing within openstack though
16:36:19 <dramakri> I am not clear if implementing the capabilities API (as my spec calls for) would adhere or violate the metadata guidelines
16:36:22 <elmiko> honestly, it feels like a cross-project spec (assuming those still exist)
16:36:40 <dramakri> In particular, it is ok to use "resource-capability" API path suffix instead of "metadata"?
16:36:47 <dramakri> Is it ok to not support create, delete
16:36:55 <elmiko> it sounded like the capabilities API is a sub-set of the metadata guide
16:37:00 <elmiko> right
16:37:01 <dramakri> Is it ok to use the simply list representations of the capabilities
16:37:37 <elmiko> as a convention, i would think it's fine to propose that projects adopt a "resource-capability" endpoint.
16:38:17 <elmiko> at this point though, maybe it would make sense to propose this as a guideline and see what the community thinks?
16:38:43 <dramakri> How and where would we propose such a thing to the community
16:39:09 <etoews> if so, it should follow the interaction conventions already in the metadata guideline (minus create, update, and delete)
16:39:21 <elmiko> if you write a guideline and submit it as a review to the api-wg, we will debate it and announce to the community to get a broader audience
16:39:34 <elmiko> etoews++
16:39:58 <etoews> dramakri: we have this too http://specs.openstack.org/openstack/api-wg/process.html#proposing-a-new-guideline
16:40:33 <dramakri> Thanks for the pointer for writing guidelines
16:41:21 <dramakri> In the meanwhile can we proceed with the implementation for resource-capabilities API in Cinder (https://review.openstack.org/#/c/350310/)?
16:41:23 <etoews> it would most likely result in the new file http://git.openstack.org/cgit/openstack/api-wg/tree/guidelines/capabilities.rst
16:43:31 <etoews> dramakri: we also recommend doing some research into what the other projects are already doing with respect to capabilities. if you do so, the place for that research is here https://wiki.openstack.org/wiki/API_Working_Group/Current_Design
16:44:16 <dramakri> ok
16:44:30 <elmiko> just from looking at the spec for that work, i don't see anything that stands out as counter to the api-wg guidelines
16:45:31 <elmiko> i'm sure there are some rest purist arguments to be made about adding the "/capabilities" to any resource endpoint, but i don't see a huge issue with that
16:45:32 <dramakri> good to know
16:45:57 <etoews> we're rest pragmatists around here ;)
16:46:02 <elmiko> ++
16:46:17 <dramakri> ++
16:46:28 <dramakri> It is "resource-capability" BTW. I so wanted to use "capability" but i would clash with some one-off API in Cinder
16:46:43 <elmiko> ah, sorry, my inaccuracy
16:46:58 <dramakri> For publishing the guideline for review, can it just summarize the spec and then point to the spec for details or do I need to paraphrase the full thing?
16:47:25 <elmiko> you should spell out how the guideline should be implenented by other projects
16:47:39 <elmiko> so, it needs to be a little more detailed. like the metadata guideline, for example.
16:48:05 <dramakri> I see
16:48:28 <etoews> ya. do something close to the metadata guideline.
16:48:51 <etoews> and it would be worthwhile to call out why you're _not_ using the metadata guideline as is
16:49:01 <elmiko> ooh, good point ++
16:49:03 <elmiko> brb
16:49:37 <dramakri> Ok so I will (1) do some research on how other projects define capabilities, (2) go ahead with my spec implementation if I don't find a pattern adopted by all other proejcts, (3) publish the guideline for defining resource capabilities at a later time
16:50:10 <etoews> dramakri: sgtm!
16:50:44 <dramakri> thanks etoews and elmiko!
16:50:58 <etoews> thanks for the good discussion dramakri
16:51:46 <elmiko> dramakri: agreed with etoews, sounds good
16:53:36 <etoews> elmiko: not much new besides this discussion. should we do a newsletter this week?
16:53:53 <etoews> (i'm okay skipping it)
16:53:59 <elmiko> hmm, i'm usually in favor of writing one
16:54:14 <etoews> okay. let's do it.
16:54:15 <elmiko> but, i don't have a strong opinion on it. did we add anything new in the last week?
16:55:50 <etoews> not that i can see
16:56:27 <elmiko> ok, i wonder if we maybe mention the capability discussion. seems like some interesting food for thought?
16:56:35 <etoews> yep
16:57:28 <elmiko> ok, looking at the etherpad now
17:00:01 <etoews> oops. gotta end the meeting.
17:00:03 <etoews> #endmeeting