| Posted | Nick | Remark | |
|---|---|---|---|
| #openstack-sdks - 2018-10-25 | |||
| 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 | edleafe | Ah. Well, there are many who say that dropping API support is a Very, Very Bad Thing | |
| 18:24:07 | kmalloc | so with microversions you wouldn't be eliminating v1, people could fall back to using it | |
| 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 | |
| 18:39:05 | kmalloc | 2) implement expirmental v2 api, v1 still works | |
| 18:39:13 | kmalloc | 3) stable v2 api, v1 still works | |
| 18:39:20 | peschk_l | edleafe: thx! (funny, it seems like you are providing a lot of links which I desperately looked for but just couldn't find) | |
| 18:39:34 | kmalloc | and you have no fundamental incompatibilities | |
| 18:39:44 | kmalloc | you can change the requirements for storage in future versions of the service | |
| 18:40:03 | kmalloc | the API should abstract it out so the user can't tell the implementation details on the backend (a good API designed does that) | |
| 18:40:13 | kmalloc | s/good API designed/well designed API | |
| 18:40:25 | edleafe | peschk_l: Here's a good link to bookmark: http://specs.openstack.org/openstack/api-sig/#guidelines | |
| 18:42:15 | peschk_l | kmalloc: does this means that we'd need to backport every new v2 api feature to v1 until support for v1 storage is dropped ? | |
| 18:42:31 | edleafe | peschk_l: no, not at all | |
| 18:42:45 | kmalloc | iterate on storage and get it to where you want. | |
| 18:42:51 | kmalloc | and just make v1 always use the new storage | |
| 18:43:02 | kmalloc | with sane defaults | |
| 18:43:13 | kmalloc | don't backport features, make it so v1 continues to work as expected | |
| 18:43:27 | kmalloc | ideally the API and the storage backend should have little bearing on eachother | |
| 18:43:49 | kmalloc | Users interact with the API, the service translates those interactions to something the storage system can understand | |
| 18:43:53 | peschk_l | OK, that's what I understood earlier. This is how it has been implemented until now | |