16:00:51 <elmiko> #startmeeting api wg
16:00:52 <openstack> Meeting started Thu Nov 19 16:00:51 2015 UTC and is due to finish in 60 minutes.  The chair is elmiko. Information about MeetBot at http://wiki.debian.org/MeetBot.
16:00:53 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
16:00:56 <openstack> The meeting name has been set to 'api_wg'
16:01:07 <elmiko> hello
16:01:09 <edleafe> o/
16:01:12 <salv-orl_> aloha
16:01:17 <rosmaita> o/
16:01:58 <elmiko> #topic agenda
16:02:06 <elmiko> #link https://wiki.openstack.org/wiki/Meetings/API-WG#Agenda
16:02:23 <elmiko> there were no action items from the previous meeting
16:02:30 <elmiko> so, let's get into the new stuff =)
16:02:40 <elmiko> #topic Glance image import refactor spec
16:02:47 <elmiko> rosmaita: i believe this is yours
16:02:55 <rosmaita> elmiko: thanks
16:03:09 <elmiko> #link https://review.openstack.org/#/c/232371/
16:03:09 <rosmaita> i'd appreciate a look over the spec when everyone can
16:03:22 <rosmaita> but i have some specific questions that maybe could be addressed right now
16:03:29 <elmiko> cool
16:03:35 <rosmaita> here: https://etherpad.openstack.org/p/api-wg-glance-import-refactor
16:03:52 <rosmaita> i put them on an etherpad so you can answer right there or add discussion points
16:04:07 <elmiko> #link https://etherpad.openstack.org/p/api-wg-glance-import-refactor
16:04:34 <rosmaita> so the background on this is that we're trying to produce an interoperable, discoverable way for end-users to get images into glance
16:04:45 <rosmaita> there will be 2 ways to do this to start
16:04:58 <rosmaita> and the spec describes the discoverablity
16:05:39 * elmiko looking at the specs
16:05:42 <rosmaita> anyway ... one of the aspects is to find out some things that are traditionally done in docs, what we're calling "value discovery"
16:05:45 <stevelle> I hold the opinion that the discoverability is essential to interop.
16:06:20 <rosmaita> there's a link on the etherpad where you can see the value-discovery response
16:06:35 <rosmaita> wondering what people think
16:07:57 <elmiko> at first look, it seems like a nice way to communicate the values. at least for human consumption, i'm curious about how this might be used programatically
16:08:05 <elmiko> or even if that is a concern?
16:08:07 <stevelle> is basing the max sizes in bytes really helpful? seems this would be easier to express in kB or mB
16:08:22 <elmiko> good question
16:08:48 <rosmaita> stevelle: it's because image size in glance is expressed in bytes
16:09:08 <rosmaita> though that doens't mean we *have* to do it here
16:09:23 <elmiko> i'm curious though, based on one of the questions in the etherpad, is this approach any better than just having fresh api docs (possibly auto-generated) for these values?
16:09:40 <rosmaita> elmiko: exactly what i'm wondering
16:09:59 <stevelle> elmiko: for programmatic discovery, there are two styles of import-methods and that can be programmatically handled as well as basic sanity checks around formats and sizes before time is spent uploading
16:10:23 <rosmaita> stevelle: so you do see someone programmatically consuming this JSON response?
16:10:28 <rosmaita> (which is good!)
16:10:41 <elmiko> rosmaita: i think, if the output can be programmatically consumed, then this has good value. otherwise i'm not so sure
16:10:47 <stevelle> I do, rosmaita.  SDKs can be updated to use this easily
16:10:57 <stevelle> CLIs follow
16:11:08 <rosmaita> cool, than we would not be wasting time by doing this
16:11:13 <elmiko> sounds like not
16:11:17 <stevelle> humans then don't need to fiddle, they can just interop
16:11:53 <stevelle> no flag switching, don't need to look up argument names in clients or parameter options on functions
16:12:04 <rosmaita> i just rolled-my-own response here, is there any kind of standard for this kind of thing?
16:13:22 <elmiko> hmm, when paired with the schema it seems pretty powerful. i'm not sure about alternatives in this space.
16:13:54 <rosmaita> ok, that brings me to the next item, the format discovery response (the JSON schema)
16:13:58 <elmiko> rosmaita: at the least, your approach seems sane to me
16:14:12 <rosmaita> elmiko: :D
16:14:47 <elmiko> i think the array types might be tricky if clients get confused about the types in the array, but that's about all i can think of currently
16:15:16 <rosmaita> i agree, tried to keep to json-schema data types
16:16:05 <elmiko> i'm not sure how that could be differentiated more though, like if one value has an array of string and another has array of int, would those types need to be specified?
16:16:41 <rosmaita> not sure ... it just so happens that all arrays are string in the doc
16:16:54 <elmiko> yea
16:17:41 <rosmaita> well, if anyone has any ideas about that, please let me know
16:17:44 <stevelle> all of those fields are required in the response schema, correct?
16:18:09 <rosmaita> stevelle: which fields do you mean?
16:18:34 <rosmaita> value discovery response or format discovery response?
16:18:51 <stevelle> sorry, "max_upload_bytes" ...
16:19:01 <stevelle> value discovery
16:19:29 <rosmaita> stevelle: that doesn't appear in the actual request or response
16:19:38 <rosmaita> it's more of an informational kind of value
16:19:51 <rosmaita> namely, your import will fail if it has more than this many bytes
16:20:15 <rosmaita> stevelle: i mean, doesn't appear in the actual *import* req/resp
16:20:30 <stevelle> I understand, but I want to ensure that all of the entries in that value discovery example are expected. I'm sorry I didn't move on to the import req/resp yet
16:20:41 <rosmaita> stevelle: np
16:21:04 <rosmaita> stevelle: yes, the intention is that whatever we settle on for this response will always include all elements
16:21:22 <rosmaita> (guess i should've written a json schema for that response?)
16:21:27 <rosmaita> (please say no!)
16:21:33 <elmiko> lol, i was just thinking that
16:21:43 <elmiko> but probably not needed, as long as the api reponse is known
16:21:49 <elmiko> *response
16:22:09 <rosmaita> though maybe it would help the array-of-what? issue
16:22:13 <rosmaita> not sure, though
16:22:36 <rosmaita> maybe mark it as an investigative item for now?
16:22:45 <elmiko> in general, it seems like we keep the contract for the apis through documentation. so, i don't think we need to start generating jsonschema for every response
16:23:07 <elmiko> although, it might make discovery easier, i'm not sure at what cost
16:23:12 <rosmaita> elmiko: ty!
16:23:32 <rosmaita> stevelle: work for you?
16:23:37 <stevelle> works for me
16:23:40 <stevelle> thanks
16:23:54 <stevelle> it could be added later if winds shift
16:24:02 <elmiko> yea
16:24:02 <rosmaita> excellent ... let's move onto the req/resp schema for import
16:24:31 <elmiko> just for clarity, this is the schema that the server accepts for POSTs?
16:24:40 <rosmaita> correct
16:24:51 <elmiko> k, cool. seems pretty clear to me =)
16:24:53 <rosmaita> and it also describes the response
16:25:04 <rosmaita> my question is about the enums in the schema
16:25:22 <elmiko> wait, i'm confused about the response part
16:25:36 * rosmaita is waiting
16:25:41 <elmiko> are you meaning to say this schema also describes the response to the v2/values/import call?
16:26:25 <rosmaita> well, prob /v2/images/{image_id}/import
16:26:31 <rosmaita> GET on that
16:26:39 <elmiko> ok, makes sense. thanks
16:26:47 <stevelle> I feel like there might be a need for a link or two
16:27:02 <elmiko> like a link to the resource in question?
16:27:28 <rosmaita> there's "self" and "schema" in there
16:28:02 <rosmaita> i tried to keep it close to the current schemas
16:28:14 <stevelle> when the import is complete, a link to the resource and when it is posted the response could contain a link to the data cache being used for the image
16:28:55 <rosmaita> stevelle: gotcha
16:29:06 <stevelle> these would be  non-required props
16:29:43 <rosmaita> stevelle: probably would go in the 'definitions' part, i think the cache would only be relevant to the glance-local method
16:29:44 <elmiko> yea, those sound useful
16:30:04 <rosmaita> ok, noted
16:30:24 <rosmaita> my main question here has to do with the values in the enums
16:30:30 <stevelle> rosmaita: I think a link to the swift url being used for the import would be helpful.  indicating that resource is still in use
16:30:52 <stevelle> after import it would be valuable to include so the client can reference it to purge
16:31:40 <rosmaita> stevelle: you'd prefer the url to the 'swift-location' element in the 'swift-local' def?
16:32:29 <rosmaita> stevelle: we can continue on the spec, don't want to take too much time here
16:32:44 <stevelle> yes, and not sure about an additional-property for glance variant
16:32:54 <rosmaita> is my question about the enums in the schema response (on the etherpad) clear?
16:33:34 <stevelle> I'm more familiar so I will pass on that.
16:33:37 <elmiko> you are asking if it's ok for the server to respond with different enum values based on its capabilities?
16:33:46 <rosmaita> elmiko: exactly
16:34:01 <elmiko> i would think yes, if it is explicitly clear to the user that this is the case
16:34:45 <rosmaita> that's what i think too ... so at least we can conclude that it's not wildly non-standard
16:34:54 <elmiko> theoretically, the errors should show what is wrong. for example, a bad enum value would generate a different error than a failure to create a certain type of image or container, etc.
16:35:39 <elmiko> i'm not sure about how non-standard it is, but it doesn't sound wildly inappropriate to me
16:35:41 <rosmaita> elmiko: i agree, the idea here is to allow you to screen for errors client-side
16:35:53 <elmiko> the schema endpoint will clearly tell you what is accepted
16:35:54 <rosmaita> but the error messages should still be clear
16:35:58 <elmiko> +1
16:36:04 <rosmaita> ok
16:36:34 <elmiko> are we good on this topic?
16:36:52 <rosmaita> last question about line 4 in the schema ... is that ok?
16:36:58 <elmiko> yup, please =)
16:37:31 <rosmaita> i'll assume yes, people with contrary opinions can write on the etherpad
16:37:36 <rosmaita> elmiko: ty, done
16:37:49 <elmiko> ok, cool.
16:37:51 <elmiko> #topic Version discovery
16:38:02 <elmiko> rosmaita, the floor is yours
16:38:17 <rosmaita> glance has an undocumented /versions endpoint
16:38:29 <rosmaita> question is do we need to keep it?
16:38:42 <rosmaita> we respect the response in the wiki page on the agenda
16:39:05 <rosmaita> but all that says is that each API should have  a versions response at /
16:39:09 <rosmaita> which we also do
16:39:25 <rosmaita> this is not a pressing issue
16:39:47 <rosmaita> mainly wanted to bring it up because there's a very detailed wiki page but nothing on this in the api wg repo
16:40:05 <rosmaita> that's all from me
16:40:08 <elmiko> hmm, if it's undocumented, i would think it's ok to deprecate. but i could see this being a tricky issue from a semver standpoint
16:40:56 <stevelle> If it was given a permanent redirect to / what thoughts?
16:41:08 <rosmaita> maybe the question is, should openstack apis have a version response at /versions ?
16:41:20 <rosmaita> or is the requirement only at /
16:41:41 <elmiko> i think that /versions could become more prevalent if project started adopting json-home docs at /
16:41:47 <elmiko> *projects
16:42:03 <elmiko> but then, the versions endpoint would be described in the json-home doc
16:42:20 <elmiko> granted, i'm not sure if any projects are considering this. although, i think some already do deliver json-home style docs.
16:43:07 <elmiko> imo, i kinda like the idea of a /versions endpoint. regardless of whether it's redirected or replicated. i like the explicit nature of it.
16:43:31 <rosmaita> ok, cool
16:43:33 <elmiko> also, just for reference
16:43:36 <elmiko> #link https://wiki.openstack.org/wiki/VersionDiscovery
16:43:45 <elmiko> #link https://review.openstack.org/#/c/244571/
16:44:08 <rosmaita> yeah, i think it would be good to get the version discovery wiki page into the api wg repo
16:44:15 <elmiko> this is definitely something we could incorporate into a guideline
16:44:20 <rosmaita> +1
16:44:21 <elmiko> agreed
16:44:33 <elmiko> would you be interested in writing a draft guideline for it?
16:44:53 <rosmaita> i could, but first i will email the author of that wiki page
16:45:00 <elmiko> ok, cool
16:45:03 <rosmaita> becasue basically, i would plagiarize that page!
16:45:24 <elmiko> #action rosmaita to investigate creating a guideline for versions endpoints
16:45:28 <elmiko> sound good?
16:45:32 <rosmaita> cool
16:45:36 <elmiko> thanks =)
16:45:54 <elmiko> ok, moving along
16:46:04 <elmiko> #topic adding software projects to the wg
16:46:19 <elmiko> so, this is a topic that came up at summit
16:46:44 <elmiko> and i'm curious to hear peoples thoughts about the idea of the api-wg taking on code projects that might support or enhance the general api landscape in openstack
16:47:11 <elmiko> annegentle and i talked briefly about something like fairy-slipper being a candidate, so think those types of projects
16:47:31 <stevelle> we're not talking a new oslo thing?
16:47:40 <elmiko> no, not specifically
16:48:13 <elmiko> my thought was that adding something a little more "crunchy" than guidelines might help garner more support and excitement about the wg
16:48:27 <elmiko> and thus, help the api landscape across the openstack community
16:49:10 <stevelle> generally I'm skeptical but individual initiatives should probably be considered on their own
16:49:49 <salv-orl_> elmiko: that would be an awesome idea
16:49:53 <elmiko> skeptical about the wg making an effort to include more projects, or something else?
16:49:57 <rosmaita> i'm not opposed, but i'm just a guy who comes to the api wg to get advice
16:50:05 <elmiko> fair
16:50:36 <stevelle> skeptical about the wg getting outside of the stated mission and processes
16:50:45 <stevelle> just thinking it should be done carefully
16:51:01 <salv-orl_> I think indeed the wg will stay within its mission
16:51:46 <elmiko> so, would it be an expansion of mission to help and generate projects that might be considered api tooling or api docs related?
16:52:35 <salv-orl_> elmiko: I am very naive, but imho as long as the wg doesn't fiddle with other projects exposing APIs and limit themselves to advice is fine
16:52:39 <stevelle> related http://specs.openstack.org/openstack/api-wg/
16:52:49 <salv-orl_> where advice can be a published guideline or a tool that gives you advice...
16:53:16 <stevelle> some code projects might fit and some would not
16:53:16 <rosmaita> stevelle: thanks, i was having trouble finding the mission stmt
16:53:25 <elmiko> yea, i'm curious to flesh this out because i think there could be merit to adding more than guidelines. but i don't want to do in the *wrong* way.
16:53:54 <elmiko> stevelle: ok, so sounds like we should move slowly, if at all, and judge each project on its own merits?
16:54:10 <rosmaita> that sounds reasonable to me
16:54:13 <stevelle> +1
16:54:35 <stevelle> we may want to discuss it again regularly to see how things proceed
16:54:45 <elmiko> agreed, that sounds good
16:54:53 <elmiko> cool, so this dovetails into another discussion that took place at summit
16:54:56 <elmiko> #topic "example project" from summit
16:55:09 <elmiko> we have always talked about not wanting to create a reference implementation
16:55:32 <elmiko> or create something that would be used as a measuring stick for projects
16:55:55 <elmiko> but we had some nice conversations about the idea of creating an example project that could display the usage of the guidelines
16:56:22 <elmiko> this project would be mostly agnostic in terms of the tooling used for implementations(eg. database, auth, etc)
16:56:55 <elmiko> but could demonstrate an outline, or on-boarding example, for someone who might be thinking about creating a service or tool to use with openstack
16:57:18 <elmiko> and thus could show through simple python code how the guidelines could be interpretted
16:57:42 <elmiko> i have a lot of ideas about this, but we are short on time. what do y'all think about his from the 1000ft level?
16:58:48 <salv-orl_> elmiko: the question is imho - does this project add anything to API samples that we can distribute as part of the guidelines?
16:59:03 <elmiko> hmm
16:59:09 <rosmaita> salv-orl_: good question
16:59:13 <salv-orl_> I'm not saying it does not just curious about your perspecitve
16:59:15 <stevelle> the most interesting part of the example would be error handling, middleware, and needing to model good use of alternate response codes and resource usage
16:59:18 <elmiko> i think it has potential, but would need fleshing out
16:59:27 <stevelle> imho
16:59:41 <rosmaita> i think maybe doing the example would help generate samples
16:59:49 <rosmaita> might be the best way to get them, tbh
16:59:51 <elmiko> stevelle: yea, i could see that, but we would need to keep things at a pluggable level
17:00:01 <elmiko> rosmaita: that's what i was thinking too
17:00:13 <elmiko> ok, well. we're out of time. thanks everyone!
17:00:16 <stevelle> I'd like to discuss further, re: pluggable but we are out of time
17:00:23 <elmiko> i'll bring this up again, for sure
17:00:26 <elmiko> #endmeeting