| Posted | Nick | Remark | |
|---|---|---|---|
| #openstack-sdks - 2018-10-25 | |||
| 16:54:52 | cdent | cool | |
| 16:55:13 | kmalloc | in fact we have an outreachy project specifically to work on our test suite. | |
| 16:57:36 | elmiko | don't know if i'll be around at 1800UTC, but if not i'll catch you next week edleafe o/ | |
| 16:57:43 | edleafe | \o | |
| 16:58:31 | elmiko | take care cdent o/ | |
| 16:58:41 | cdent | elmiko: have you been fired? | |
| 16:58:50 | elmiko | not that i know of | |
| 16:58:59 | cdent | "cleaning desk" | |
| 16:59:09 | elmiko | oh, lol, bad "office hours" joke | |
| 16:59:56 | elmiko | i imagine myself coming in to some univeristy office that we all share to hold office hours, just trying to leave the camp site better than i found it ;) | |
| 18:12:53 | peschk_l | kmalloc, edleafe: I'm back | |
| 18:13:10 | edleafe | I'm here | |
| 18:13:24 | kmalloc | peschk_l: o/ | |
| 18:14:16 | peschk_l | about my questions: Basically, cloudkitty has changed the way it processes and manages data internally. We also created a new storgae backend. Which means we need to refactor the current API | |
| 18:15:39 | peschk_l | currently, we use pecan + wsme, which I personally don't like at all, given that it's hard to understand at first... which doesn't help us to gain some new contributors | |
| 18:15:52 | edleafe | peschk_l: why would an internal change require changing the API? | |
| 18:16:46 | kmalloc | ^ | |
| 18:16:49 | kmalloc | good question | |
| 18:17:09 | peschk_l | edleafe: because there are a lot of things which our new storage interface supports, for example (re-)grouping | |
| 18:17:14 | kmalloc | unless the API leaks implementation details, which then I do encourage fixing that :) | |
| 18:17:46 | kmalloc | so how can i help you? :) i'm happy to answer questions re: flask or other things. | |
| 18:17:55 | edleafe | ah, so you're adding new functionality? | |
| 18:18:07 | peschk_l | edleafe: exactly | |
| 18:18:20 | peschk_l | we would at least need to implement a new API endpoint | |
| 18:18:56 | edleafe | Are you using microversions now? | |
| 18:19:02 | peschk_l | no | |
| 18:20:01 | peschk_l | given that we are a tiny project, the plan was more or less the following: have v1 and v2 APIs served at the same time. Given that we won't be able to move all v1 resources to v2 in a single release, we would like to do that resource after resource | |
| 18:20:18 | peschk_l | releasing a microversion for each migrated resource | |
| 18:21:05 | peschk_l | the thing is that we don't really know if microversions are used/supported in openstack right now | |
| 18:21:14 | kmalloc | some projects use microversions | |
| 18:21:26 | edleafe | So users of the API could continue to request things they currently do, and will get back a response that has the same format as now? | |
| 18:21:27 | kmalloc | cdent has extracted things into a nice middleware for processing the request itself | |
| 18:22:10 | peschk_l | kmalloc: yeah, I had a look at cdent's link, it look like like it could ease our work :) | |
| 18:22:14 | edleafe | Microversions are used by nova, placement, ironic, and maybe more | |
| 18:22:30 | kmalloc | microversions are explicitly NOT used by keystone (for example) | |
| 18:22:44 | edleafe | So yeah, microversions are supported :) | |
| 18:22:51 | kmalloc | so yeah depends on the project | |
| 18:23:12 | kmalloc | there is no reason you should feel like microversions are a tool you should avoid unless you want to avoid them | |
| 18:23:29 | peschk_l | edleafe: they could. At least for a while. idea would be to say: resource AAA has been made available in v2 since release 2.xx of the API. Support for the v1 endpoint of this resource will be dropped with API version 2.yy | |
| 18:23:38 | kmalloc | if it makes things easier for you and your users, they can be good. | |
| 18:23:42 | peschk_l | until we have no more resources in v1 | |
| 18:23:49 | peschk_l | kmalloc: glad to hear that | |
| 18:24:07 | kmalloc | so with microversions you wouldn't be eliminating v1, people could fall back to using it | |
| 18:24:07 | edleafe | Ah. Well, there are many who say that dropping API support is a Very, Very Bad Thing | |
| 18:24:40 | kmalloc | you can drop support in v2, but you'll want to maintain v1 with the limited (default) capabilities where the API can't inform data to the backend | |
| 18:24:48 | kmalloc | s/default/sane defaults | |
| 18:24:52 | peschk_l | well the goal would beb to eliminate v1 after some time | |
| 18:24:59 | peschk_l | *be | |
| 18:25:03 | edleafe | microversions only apply within a major release | |
| 18:25:16 | edleafe | Going from v1 to v2 is anything but micro | |
| 18:25:22 | kmalloc | removing APIs is bad in general | |
| 18:25:55 | kmalloc | as someone who championed removal of an api in a major project, i highly recommend not doing that. it surprises users in bad ways | |
| 18:26:01 | edleafe | peschk_l: https://blog.leafe.com/api-longevity/ | |
| 18:26:06 | kmalloc | edleafe: ++ | |
| 18:26:50 | kmalloc | as much as keystone team (and me personally) would love to drop some things to the side from our API, we wont remove apis from default deployment/functionality in the foreseeable future | |
| 18:27:10 | edleafe | Unless v1 is highly unstable or causes some other extreme issue, you really should keep it around | |
| 18:27:16 | kmalloc | ++ | |
| 18:27:40 | peschk_l | edleafe: we'd like to refactor the whole API... But we won't be able to accomplish that in a single release. So the idea would be to implement new endpoints within v2 only, and to slowly migrate "legacy" endpoints from v1 to v2 | |
| 18:27:49 | peschk_l | (thanks for the link btw) | |
| 18:28:45 | kmalloc | i also highly recommend, whatever you do, not version your endpoints in the catalog | |
| 18:28:59 | kmalloc | support v1/v2 (as you transition) on the same server/wsgi application | |
| 18:29:07 | kmalloc | versioned endpoints are a bad idea. | |
| 18:29:08 | peschk_l | Honestly, v1 has some major issues, for example (and I'm ashamed), there is no way to paginate results, except with begin/end timestamps | |
| 18:29:22 | edleafe | peschk_l: A general approach for creating the new API is along these lines: | |
| 18:29:39 | edleafe | 1) create a new endpoint, labeled 'EXPERIMENTAL' | |
| 18:29:53 | edleafe | 2) start adding more and more features to that endpoint | |
| 18:29:54 | peschk_l | kmalloc: we weren't planning to manage the endpoints. versions would only have been "markers" for which endpoints are supported, and which are not | |
| 18:30:41 | edleafe | 3) When you finally have a good, working version, change that version to 'CURRENT' and change the old version to 'SUPPORTED' | |
| 18:31:06 | edleafe | This way users can opt into the new API if they wish at their own pace, knowing that it is subject to change | |
| 18:31:10 | kmalloc | ++ | |
| 18:31:28 | kmalloc | ^ that is what i was in the middle of typing before edleafe beat me to it | |
| 18:31:40 | edleafe | You don't flip the switch until the new API is solid, and your can't see any more work needed on it | |
| 18:31:54 | kmalloc | and at that point you can support microversions on v2 | |
| 18:32:05 | kmalloc | and v1 is legacy, maintained for compat with old clients/users | |
| 18:32:35 | kmalloc | you give all the shiny new things to v2/v2+microversions so folks are encouraged to use v2 | |
| 18:32:36 | peschk_l | I see. Would you still add endpoint for new features on v2 only, and mark them as experimental ? | |
| 18:32:53 | peschk_l | kmalloc: ok, got my answer :) | |
| 18:32:55 | kmalloc | i would support in your service /v1 <current> | |
| 18:32:59 | kmalloc | and /v2 <new> | |
| 18:33:05 | kmalloc | and have / be a discovery doc | |
| 18:33:17 | kmalloc | so folks can determine what is there (standard for openstack projects these days) | |
| 18:33:27 | kmalloc | keystoneauth has a standard way of doing the discovery bits | |
| 18:33:36 | kmalloc | (ignoring ironic's legacy stuff) | |
| 18:34:01 | peschk_l | OK, I'll look into that | |
| 18:34:19 | kmalloc | that way your endpoints aren't serviceV2 it is just "service" | |
| 18:34:29 | kmalloc | and the user can see "oh service supports v2, i want to use v2" | |
| 18:34:42 | kmalloc | vs needing to go to a totally different endpoint (service/port/host) for v2 | |
| 18:34:51 | edleafe | And existing tools/SDKs can still work against v1 forever | |
| 18:35:36 | kmalloc | just make sure v1 informs smart/sane defaults for the values that the user can't pass to the new backends | |
| 18:35:47 | kmalloc | or the backends have sane defaults built in | |
| 18:35:57 | kmalloc | that way new storage doesn't break if someone uses v1 | |
| 18:36:42 | peschk_l | I see. But then the only way do distinguish between v1+v2 with 1 endpoint and v1+v2 with 4 endpoints and fixes would be the openstack release ? | |
| 18:36:58 | kmalloc | in the discovery doc | |
| 18:37:35 | kmalloc | so you'd look at Service X / and see it supports v1, or v1+v2 or v1+v2(and microversions on v2) | |
| 18:37:45 | peschk_l | current v1 API is compatible with the v2 storage. However, v2 API features won't be compatible with the v1 storage | |
| 18:37:49 | edleafe | peschk_l: if you ever have insomnia and need something to help you sleep, this is excellent reading: http://specs.openstack.org/openstack/api-sig/guidelines/consuming-catalog.html#consuming-catalog | |
| 18:38:33 | kmalloc | if you only ever implement new storage once v2 is there, the v1 stuff populates defaults to the storage, v2 allows greater depth of configuration | |
| 18:38:46 | kmalloc | if someone is hitting an endpoint with only v1, theyn get current behavior | |
| 18:38:51 | kmalloc | typically the way this is done is | |
| 18:38:56 | kmalloc | 1) implement new storage, make v1 compat | |