| 00:10.59 | *** join/#asterisk-dev snuff-work (~snuffy@210.8.167.13) |
| 00:10.59 | *** mode/#asterisk-dev [+o snuff-work] by ChanServ |
| 02:08.38 | *** join/#asterisk-dev serafie (~erin@user-24-214-173-250.knology.net) |
| 03:44.17 | *** join/#asterisk-dev serafie (~erin@user-24-214-173-250.knology.net) |
| 04:00.30 | *** join/#asterisk-dev oej (~oej@h87-96-134-129.dynamic.se.alltele.net) |
| 04:00.31 | *** mode/#asterisk-dev [+o oej] by ChanServ |
| 05:51.58 | *** join/#asterisk-dev oej (~oej@h87-96-134-129.dynamic.se.alltele.net) |
| 05:51.58 | *** mode/#asterisk-dev [+o oej] by ChanServ |
| 06:03.06 | *** join/#asterisk-dev vlad_starkov (~vlad_star@109.188.125.199) |
| 06:13.12 | *** join/#asterisk-dev vlad_starkov (~vlad_star@109.188.125.199) |
| 06:33.42 | *** join/#asterisk-dev oej (~oej@h87-96-134-129.dynamic.se.alltele.net) |
| 06:33.43 | *** mode/#asterisk-dev [+o oej] by ChanServ |
| 06:39.29 | *** join/#asterisk-dev vlad_starkov (~vlad_star@195.68.180.114) |
| 06:40.41 | *** join/#asterisk-dev vlad_sta_ (~vlad_star@195.68.167.197) |
| 07:02.50 | *** join/#asterisk-dev tzafrir (~tzafrir@2001:41b8:203:dc13:6267:20ff:fe51:8328) |
| 07:02.50 | *** mode/#asterisk-dev [+o tzafrir] by ChanServ |
| 07:38.46 | *** join/#asterisk-dev l0c0 (~nde@host-212-68-194-46.brutele.be) |
| 08:23.26 | oej | Morning folks |
| 08:57.14 | *** join/#asterisk-dev elguero (~miguel323@2001:470:1f06:12c4::2) |
| 09:52.30 | *** join/#asterisk-dev vlad_starkov (~vlad_star@195.68.167.197) |
| 11:11.33 | *** join/#asterisk-dev pc-m (~pcm@modemcable094.94-70-69.static.videotron.ca) |
| 11:49.42 | *** join/#asterisk-dev pabelanger (~pabelange@asterisk/contributor-and-bug-marshal/pabelanger) |
| 11:49.42 | *** mode/#asterisk-dev [+o pabelanger] by ChanServ |
| 12:10.01 | *** join/#asterisk-dev pc-m (~pcm@modemcable094.94-70-69.static.videotron.ca) |
| 12:10.26 | pabelanger | Morning |
| 12:10.34 | pabelanger | more ARI question today |
| 12:10.47 | pabelanger | Is the process of POST /channels blocking? |
| 12:11.26 | pabelanger | or is the dial async? |
| 12:24.02 | *** join/#asterisk-dev vlad_starkov (~vlad_star@195.68.167.197) |
| 12:34.02 | *** join/#asterisk-dev vlad_starkov (~vlad_star@195.68.167.197) |
| 12:35.25 | *** join/#asterisk-dev pabelanger (~pabelange@asterisk/contributor-and-bug-marshal/pabelanger) |
| 12:35.25 | *** mode/#asterisk-dev [+o pabelanger] by ChanServ |
| 12:59.49 | *** join/#asterisk-dev anonymouz666 (~anonymouz@186-247-254-99.user.veloxzone.com.br) |
| 13:09.51 | *** join/#asterisk-dev dwayne (~dwayne@c-71-207-208-112.hsd1.al.comcast.net) |
| 13:51.09 | *** join/#asterisk-dev serafie (~erin@nat/digium/x-nqdvxsrxqezvfwif) |
| 14:08.43 | *** join/#asterisk-dev vlad_starkov (~vlad_star@109.188.126.49) |
| 14:13.45 | *** join/#asterisk-dev luckman212 (~luckman21@unaffiliated/luckman212) |
| 14:26.49 | *** join/#asterisk-dev sruffell (~sruffell@asterisk/the-kernel-guy/sruffell) |
| 14:26.49 | *** mode/#asterisk-dev [+o sruffell] by ChanServ |
| 14:29.14 | *** join/#asterisk-dev kharwell (~kharwell@nat/digium/x-tsfbrbmgrhxjgutr) |
| 14:29.19 | *** part/#asterisk-dev kharwell (~kharwell@nat/digium/x-tsfbrbmgrhxjgutr) |
| 14:29.31 | *** join/#asterisk-dev kharwell (~kharwell@nat/digium/x-tsfbrbmgrhxjgutr) |
| 14:31.27 | jrose_atDigium | pabelanger: Well, as far as I can tell the dial is not run asynchronously, but since it takes place in a thread from the ARI threadpool, all it should be blocking is the thread that it's running on. |
| 14:48.24 | leedm777 | pabelanger: It's an async dial; the POST returns immediately. If you provide the app parameter, that app will get a StasisStart event when they pick up. |
| 14:48.31 | leedm777 | reads backlog for other ARI questions |
| 14:52.09 | jrose_atDigium | leedm777: ast_dial_run function itself is called with the async flag set to 0. Is it just async for practical purposes since tit's ran through the control queue? |
| 14:52.19 | jrose_atDigium | s/tit's/ it's/ |
| 14:53.47 | jrose_atDigium | And I guess the control is being ran on its own thread as well. |
| 14:55.17 | *** join/#asterisk-dev putnopvut (~putnopvut@asterisk/master-of-queues/mmichelson) |
| 14:55.17 | *** mode/#asterisk-dev [+o putnopvut] by ChanServ |
| 14:57.47 | pabelanger | leedm777: Ya, I had a ton of questions on Friday, after you left |
| 14:58.44 | leedm777 | bbiab |
| 15:00.41 | pabelanger | I had a chance to start using ARI on Friday, one of the first things I noticed was we seemed to create a new layout for information in the ARI. For example look at *CLI> core show settings |
| 15:00.51 | pabelanger | that information appears to be different then http://svnview.digium.com/svn/asterisk/trunk/rest-api/api-docs/asterisk.json |
| 15:04.31 | pabelanger | so the setid property should go, and just condense it to user and group |
| 15:05.17 | *** join/#asterisk-dev zigg (~matt@unaffiliated/zigg) |
| 15:11.19 | leedm777 | Juggie: re: abstraction layer. In 12 we introduced Stasis as a common abstraction layer. ARI is built on that, and most AMI events were refactored to use it. |
| 15:14.41 | *** join/#asterisk-dev mjordan (~mjordan@nat/digium/x-njdjnubvjpfueqxu) |
| 15:14.41 | *** mode/#asterisk-dev [+o mjordan] by ChanServ |
| 15:16.50 | leedm777 | pabelanger: Since the ARI responses are JSON, we take advantage of the fact that responses can use structured data. Are you expecting key/value pairs? |
| 15:19.07 | pabelanger | leedm777: Right, I believe the ARI responses that use structured data might be overly complex for an app developer. Does setid really need its own structure, or can we make the response more simpler |
| 15:19.45 | pabelanger | First impressions, from me, it is overly complicated |
| 15:21.35 | leedm777 | pabelanger: so you're suggesting that we just have fields setid_user and setid_group, or just have fields user and group and let them figure out that we're talking about set[ug]id? |
| 15:22.57 | leedm777 | I prefer the API to be explicit, so user and group should be qualified with setid. Given that, a little structure with two fields makes the most sense. |
| 15:23.07 | pabelanger | leedm777: well, just look to CLI*> core show settings |
| 15:23.14 | pabelanger | there is not reference to setid |
| 15:23.19 | pabelanger | just user / group |
| 15:23.29 | Qwell | Doing things the wrong way, because we've always done things the wrong way, is the wrong way to go. |
| 15:23.34 | leedm777 | CLI is designed with a different set of constraints. |
| 15:24.01 | pabelanger | I think we should be looking to our existing output formats and trying to keep them in sync other wise, it will be difficult to remember the variable names across all interfaces |
| 15:24.06 | leedm777 | Plus, what Qwell said. |
| 15:25.36 | *** join/#asterisk-dev vlad_starkov (~vlad_star@109.188.126.49) |
| 15:25.41 | *** join/#asterisk-dev [TK]D-Fender (~chatzilla@64.235.216.2) |
| 15:26.38 | leedm777 | pabelanger: Did I also hear that you had some questions about authentication on Friday? Did you get answers to those? |
| 15:27.02 | jrose_atDigium | I believe Juggie provided answers to his authentication question. |
| 15:27.39 | pabelanger | leedm777: Mostly I wanted to better understand the auth process, it looks like we support password and crypt... but both seems to transmit your credentials in plain text |
| 15:28.02 | pabelanger | was curious if we are going to use oauth 2.0 or something |
| 15:28.27 | leedm777 | pabelanger: no oauth in 12. Not even sure if that would make 13. |
| 15:28.40 | pabelanger | Hmm |
| 15:28.43 | leedm777 | pabelanger: if you want to keep your credentials secure, you need to use HTTPS. |
| 15:28.53 | pabelanger | can you explain how crypt works? |
| 15:29.14 | pabelanger | because from what I seen, it was just to encrypt the password in ari.conf |
| 15:29.26 | leedm777 | pabelanger: that's just crypting the password in the config file, just like passwords in /etc/shadow |
| 15:29.46 | leedm777 | If we can't encrypt passwords on the wire, at least we'll encrypt them on disk :-D |
| 15:30.45 | pabelanger | we might want to be more explicit in the ari.conf file, that even though you use crypt method, the credentials still need to be transmitted in clear text |
| 15:30.57 | Qwell | They don't need to be. |
| 15:31.07 | pabelanger | Qwell: explain? |
| 15:31.11 | Qwell | https |
| 15:31.33 | wdoekes | ah, so ASTERISK-21965 overwrote my safe_asterisk mods. ok ok.. but why didn't r394939 get any review? pvalue=`grep ^PRIORITY= $ASTETCDIR 2>/dev/null | cut -c 10` <-- grepping a dir without any --recursive? |
| 15:31.35 | pabelanger | no, even if you use https: you still need to transmit the username and password as plain text |
| 15:31.42 | Qwell | wat |
| 15:31.48 | pabelanger | api_key=username:password |
| 15:31.58 | leedm777 | pabelanger: that gets encrypted on the wire |
| 15:34.00 | pabelanger | so, how is using Basic Auth vs api_key and different? |
| 15:34.11 | jrose_atDigium | wdoekes: Might want to ping mjordan on that one. He won't be around long today and it might be a week or so before he's available again. |
| 15:34.15 | leedm777 | pabelanger: it's not. |
| 15:34.19 | mjordan | wdoekes: it was clearly less innocuous than it appeared to be. |
| 15:34.30 | jrose_atDigium | nm |
| 15:34.57 | pabelanger | leedm777: right, so why support to weak authentication methods? Shouldn't basic auth be enough? |
| 15:35.22 | leedm777 | pabelanger: BA and ?api_key are equally weak. |
| 15:35.29 | pabelanger | right |
| 15:35.33 | pabelanger | so, why is 2 needed? |
| 15:35.40 | leedm777 | Swagger-UI uses the ?api_key authentication |
| 15:36.13 | leedm777 | And Swagger-UI is very useful for learning the API |
| 15:36.25 | jrose_atDigium | <3 Swagger-UI |
| 15:36.40 | jrose_atDigium | Also great for just general prototyping. |
| 15:36.56 | leedm777 | Executable documentation, FTW! |
| 15:38.47 | leedm777 | pabelanger: The ?api_key thing is there pretty much just for Swagger-UI. Although occasionally I'll use it rather than looking up the man page to figure out how to pass basic auth param to curl/wget/wscat/etc. |
| 15:41.46 | pabelanger | leedm777: is this program in the asterisk source tree to walk the API docs? |
| 15:41.53 | pabelanger | how are you using the api_key in swagger? |
| 15:42.18 | pabelanger | a quick look at their documentation shows they support Authorization headers: https://github.com/wordnik/swagger-ui#custom-header-parameters---for-basic-auth-etc |
| 15:42.36 | pabelanger | so, that would remove the dependency on the api_key setting |
| 15:44.34 | pabelanger | leedm777: another question, are you implementing versioning with the APIs? |
| 15:44.39 | jrose_atDigium | pabelanger: You could host it yourself, but the easiest method is just to point their demo at your asterisk server: http://petstore.swagger.wordnik.com/ - change address to http://localhost:8088/ari/api-docs/resources.json and username:password for api_key |
| 15:44.42 | pabelanger | eg: /ari/v1/asterisk/info? |
| 15:45.59 | pabelanger | jrose_atDigium: no, I am proposing getting rid of api_key, since we are just using it as an alias for Basic authentication |
| 15:47.21 | pabelanger | this is what I am trying to explain: https://blog.apigee.com/detail/do_you_need_api_keys_api_identity_vs._authorization |
| 15:50.39 | jrose_atDigium | Well, we don't really have any control over what Swagger-UI will use for authentication though. It doesn't provide fields for appending custom headers as far as I'm aware. |
| 15:50.48 | leedm777 | pabelanger: to get Swagger-UI to send basic auth headers would require source changes. We're not introducing an actual API key, but using the API key mechanism to send the username and password. We get value, there's almost no cost. No real reason to remove it. |
| 15:52.27 | pabelanger | leedm777: which source changes? |
| 15:53.12 | jrose_atDigium | to Swagger UI. We'd have to provide a way to supply the authentication headers. |
| 15:53.32 | jrose_atDigium | s/authentication/authorization/ |
| 15:54.07 | pabelanger | jrose_atDigium: how are you interfacing to swagger UI? Just using your browser? |
| 15:54.16 | leedm777 | pabelanger: yes. just the browser. |
| 15:54.39 | leedm777 | 1. Point your browser at http://petstore.swagger.wordnik.com/ |
| 15:55.01 | leedm777 | 2. Change the URL in the app to http://localhost:8088/ari/api-docs/resources.json |
| 15:55.10 | leedm777 | 3. Put username:password in the spot for api_key |
| 15:55.15 | leedm777 | 4. Click explore |
| 15:55.17 | pabelanger | okay, so that is the issue. you are not hosting your over version rather using a public setup |
| 15:55.19 | leedm777 | 5. PROFIT! |
| 15:55.25 | pabelanger | since https://github.com/wordnik/swagger-ui#swaggerui explains how to actually do it |
| 15:55.31 | pabelanger | with headers |
| 15:55.59 | pabelanger | heh |
| 16:01.06 | jrose_atDigium | We'd also still have to modify our own swagger UI sources in order to be able to supply auth headers in that manner. |
| 16:01.23 | jrose_atDigium | Doing things this way is just more approachable. |
| 16:01.43 | mjordan | wdoekes: is there anything else that you can see in r394939 that needs to be modified? If so, we can back out the change for now to give it a more proper review |
| 16:01.48 | leedm777 | Not to mention less work :-) |
| 16:02.40 | pabelanger | okay, well I'm done for now on the api_key discussion. I raised my points |
| 16:02.49 | pabelanger | so now, on to API versioning |
| 16:02.59 | pabelanger | How is that going to be implemented? |
| 16:03.30 | pabelanger | I would assume http://localhost:8088/ari/v1/asterisk/info |
| 16:03.49 | leedm777 | Now _that's_ a good question. |
| 16:05.04 | *** join/#asterisk-dev Marquis42 (~mrbmw@c-68-43-88-71.hsd1.mi.comcast.net) |
| 16:05.10 | leedm777 | Much of it is still TBD, but I would expect it would be something like /ari to get to the current version of the API, with /ari/vX to get to specific API versions. |
| 16:05.27 | leedm777 | Version bump should only happen when we introduce backward incompatible changes. |
| 16:06.24 | Corydon76-home | Given past history, I think a better way to go would be to add strings to the version that indicated featuresets |
| 16:06.48 | leedm777 | Corydon76-home: Could you elaborate a bit? |
| 16:07.44 | Corydon76-home | The problem with a simple version number is that sometimes, a security issue required backporting a certain featureset to a preexisting release, which meant the linear scope of a version number was inadequate to determining whether a particular feature was present |
| 16:08.25 | Corydon76-home | Think about the output of /proc/cpuinfo, where the processor indicates a set of features available on the processor |
| 16:08.51 | *** part/#asterisk-dev mjordan (~mjordan@nat/digium/x-njdjnubvjpfueqxu) |
| 16:10.02 | Corydon76-home | That also would allow a featureset with problematic security to be dropped in the future, and all that it requires is to drop the corresponding feature flag from the version info |
| 16:10.54 | Corydon76-home | So to determine if it supports a particular feature, software has to scan the string flags to determine if a feature is present. |
| 16:12.05 | leedm777 | Corydon76-home: In this context, we're talking about how an API gets versioned, and how that might affect the URL's for accessing the API. |
| 16:12.07 | Corydon76-home | That's a lot better than reading the version number and then consulting a complex list of internal logic to determine whether a feature is available or not. It also make the aforementioned removal possible. |
| 16:12.39 | leedm777 | Corydon76-home: In terms of featuresets for Asterisk, it's even more complicated b/c a particular running system might have different features depending on which modules have been loaded. |
| 16:13.12 | Corydon76-home | leedm777: yes, it's complicated on the backend, but it makes the API for checking a lot simpler |
| 16:14.33 | leedm777 | Corydon76-home: That's two separate problems though. A particular API may change over time, and you need to ensure that your version of code works with a given version of the API. Then there's the problem you bring up where a function of the API may not even be there, depending on configuration, versioning, phase of the moon, etc. |
| 16:14.39 | Corydon76-home | If I want to use a particular feature, all I need to do is check for a string, and I DON'T need to worry that a future version, which I was not aware of, might drop a particular feature because of a security concern. |
| 16:15.43 | pabelanger | leedm777: right, we should also come up with when version bumps happen. Hopefully not mid release |
| 16:16.30 | Corydon76-home | pabelanger: because of security issues, version bumps would otherwise ALWAYS occur mid-release, and you should assume not just of the possibility, but of the certainty that it will occur |
| 16:18.15 | pabelanger | Corydon76-home: correct, but it would have to be a bad security issue to possibly break variable names and stuff |
| 16:18.28 | pabelanger | so, /ari/v1.0 |
| 16:18.33 | Corydon76-home | pabelanger: assume the worst and hope for the best |
| 16:18.38 | pabelanger | nods |
| 16:20.17 | Corydon76-home | If you're insistent upon using version numbers like that, I would caution against going to 1.1 too soon. Next version bump should be 1.001 or even 1.0001 |
| 16:20.29 | coreyf1513 | +1 to feature flags over version numbers. adding a new feature without breaking changes to any existing features should not break clients of the existing features. |
| 16:21.05 | Corydon76-home | It is inevitable that someone will otherwise treat it as a float, which causes problems when you go to 1.10. 1.010 or 1.0010 is preferable |
| 16:21.25 | leedm777 | pabelanger: why the minor version number? we just need to indicate API breaking changes, so a single major version number should be sufficient. |
| 16:22.07 | leedm777 | pabelanger: the api-doc itself can specify a full API version, which for an API could be major.minor.bugfix. |
| 16:29.35 | leedm777 | Corydon76-home coreyf1513: ARI supplies a very rich description of the API's in a machine readable format, including resources, operations, parameters and output models. To see if feature X is supported, one could check for the presence of the associated operations. Would that work sufficiently well enough for feature flags? |
| 16:29.50 | Corydon76-home | leedm777: going back to the previous issue, I understand where you're coming from on the API versions, but there's the additional possibility (based upon past history) that a particular function in a v1 api may have to be wholesale removed, because it has a security vulnerability associated with it. We need to provide an API function that explicitly lists the features still available in that version of the API |
| 16:30.55 | Corydon76-home | and we should specifically document that users of a particular version of the API _should_ check that featureset to verify that a feature upon which they depend is still present |
| 16:31.57 | Corydon76-home | leedm777: your best bet is to write a sample application yourself, and go through the scenarios and verify that your checking is sufficient |
| 16:32.34 | Corydon76-home | Or if it's needlessly obtuse and a simpler mechanism would be preferable |
| 16:33.53 | Corydon76-home | We should document what application developers should do in terms of api checks, because it makes the external application developers' lives easier, if we have a suggested set of logic that we suggest that they use to verify the existence of featuresets and/or particular functions |
| 16:35.07 | leedm777 | Corydon76-home: Maybe it would help if I had better context. Can you name two or three featuresets we've had to remove mid-release in the past due to security issues? |
| 16:37.20 | Corydon76-home | I'd have to review past security advisories |
| 16:37.56 | Corydon76-home | Are you looking for Asterisk in particular or other versioned APIs, as well? |
| 16:38.03 | Corydon76-home | It's happened in both cases |
| 16:38.07 | leedm777 | Corydon76-home: Asterisk, specifically. |
| 16:39.19 | pabelanger | SIP_CAUSE performance regression? |
| 16:39.26 | pabelanger | not security but change of functionality |
| 16:40.39 | pabelanger | leedm777: shouldnt /ari/asterisk/variable be /ari/dialplan/variable ? |
| 16:41.06 | pabelanger | I'm assuming you'd want a /dialplan namespace at some point in dial to interact with dialplan |
| 16:41.38 | file | interact with dialplan? |
| 16:42.18 | pabelanger | create / edit / delete dialplan |
| 16:42.22 | pabelanger | view |
| 16:42.42 | leedm777 | pabelanger: imagine a world in which there is no dialplan. you'd probably still have global channel variables. |
| 16:43.13 | pabelanger | okay, so /ari/channel/variables? |
| 16:43.34 | pabelanger | <PROTECTED> |
| 16:43.51 | leedm777 | pabelanger: yeah, it's not great. |
| 16:44.39 | leedm777 | . /ari/channels/variables has a naming collision with /ari/channels/{channelId} |
| 16:45.13 | leedm777 | of course, you'll never have a channel with an id of 'variables', the API is clearer if we can avoid those sorts of collisions. |
| 16:48.43 | pabelanger | Guess you'd have to do /ari/channel?variables |
| 16:49.04 | pabelanger | or what ever the syntax is |
| 16:50.04 | leedm777 | Still a naming collision |
| 16:50.51 | pabelanger | <PROTECTED> |
| 16:51.06 | leedm777 | GET /ari/channels lists active channels |
| 16:51.13 | leedm777 | POST /ari/channels originates a call |
| 16:52.02 | leedm777 | Overloading that with global channel variable stuff would be wrong. |
| 16:53.34 | pabelanger | so, what was the issue with /ari/dialplan again? |
| 16:55.41 | leedm777 | pabelanger: imagine a world in which there is no dialplan. you'd probably still have global channel variables. |
| 16:57.18 | leedm777 | The /asterisk resource is the place for these system-wide things that don't really merit having a resource of their own. |
| 16:58.21 | leedm777 | As far as create/edit/delete dialplan, I'm not sure we'd ever put that in ARI due to security issues (i.e. someone creates dialplan that invokes SYSTEM(), they can rule your world) |
| 16:59.25 | file | plus it would be better in the end for you to write your own "dialplan" in the language you want |
| 17:00.17 | coreyf1513 | leedm777: maybe i'm misunderstanding about the versions, I thought you were talking about having the ARI version as part of the URL? IE /ari/v1.0/channel/variable? |
| 17:01.02 | leedm777 | coreyf1513: there were two conversations mingled together then. One about versioning, the other about feature availability. |
| 17:02.14 | leedm777 | oh, and the third where pabelanger wants to move /asterisk/variable somewhere else. |
| 17:02.28 | Qwell | and how Qwell likes cookies |
| 17:02.42 | leedm777 | Yes, and cookies. |
| 17:02.55 | leedm777 | COOKIES FOR ALL! |
| 17:02.58 | Corydon76-home | and the Muffin Monster |
| 17:03.19 | Qwell | You know you butchered a spelling of something, when xchat won't even try to correct it for you. |
| 17:03.35 | Qwell | In other news, I love macadamia nut cookies. |
| 17:04.44 | coreyf1513 | leedm777: at this point i'm concerned about the /ari/v1.0 part, which in theory would become /ari/v1.1. Any existing consumer programmed for v1.0 would break |
| 17:05.16 | leedm777 | coreyf1513: which is why I like major-version only :-) |
| 17:05.57 | leedm777 | Ideally, we would support /ari/v1 and /ari/v2 concurrently, giving consumers time to move their applications from the old API to the new one. |
| 17:06.33 | leedm777 | The real world is rarely that clean and perfect, but that would be the goal. |
| 17:07.29 | Corydon76-home | leedm777: I think you're likely to have at least 3 versions in production at any one time. There's also the case to be made for NOT incrementing the version number for an API that hasn't actually changed |
| 17:07.58 | Corydon76-home | So you have /ari/v1 for most functions and /ari/v3 for a particular function that had to be incremented |
| 17:09.12 | leedm777 | Corydon76-home: I don't know about that. I think I would rather just code to a /ari/v3 API, rather than figure out in which version a particular operation was last changed. |
| 17:09.20 | file | agreed |
| 17:09.46 | file | having a combined view of the system as a whole which is made up of differently versioned resources can become... a mess |
| 17:09.47 | Corydon76-home | leedm777: Don't think about it like that. |
| 17:10.53 | Corydon76-home | Think about it as somebody having coded a complex application to v1. Now you release v2 in the middle of a release cycle to deal with a problem. Now they have to deal with two different, entirely incompatible APIs, in their one application, in order to support any Asterisk versions in production |
| 17:11.18 | Corydon76-home | If you instead only bump the api for the function that needs to be changed, you dramatically reduce the work for the application developer |
| 17:11.35 | leedm777 | Not if /v1 is still there, untouched. |
| 17:11.45 | leedm777 | Then there's no work for them at all. |
| 17:11.56 | leedm777 | They can ignore /v2 for as long as we continue to support /v1 |
| 17:12.30 | Corydon76-home | The truth of the matter is, they'll want to use that new v2 api for the functions where they need the additional functionality |
| 17:12.42 | Corydon76-home | but they'll want to leave other modules unaltered |
| 17:12.43 | Qwell | raises his hand |
| 17:13.01 | leedm777 | recognizes the honorable Mr. Qwell |
| 17:13.17 | Qwell | Asterisk 12 is v3, Asterisk 13 is v4. A security issue happens, requiring the version be bumped. Asterisk 12 will become...v5? |
| 17:13.23 | Qwell | and Asterisk 13 will be v6? |
| 17:13.37 | Corydon76-home | Precisely |
| 17:13.48 | leedm777 | version number should only be bumped if there's a backward incompatible API change. |
| 17:14.10 | Corydon76-home | Security advisory requires that you remove a singular api function from v1 |
| 17:14.11 | Qwell | leedm777: for the sake of argument, let's assume that there was |
| 17:14.37 | Corydon76-home | Or otherwise make that function inoperable |
| 17:15.40 | leedm777 | Corydon76-home: Okay, let's say that we have /ari/v1/asterisk/hackme, which gives root access to the system. And, after release, we decide that was a bad idea. |
| 17:16.02 | leedm777 | in /ari/v2/asterisk, there won't be a /hackme resource at all. we can drop that feature completely. |
| 17:16.04 | pabelanger | wouldn't v3.1 be better, and 4.1 for security? only bumping X (in X.Y) each asterisk release? |
| 17:16.50 | Corydon76-home | leedm777: but you're ignoring Qwell's situation |
| 17:17.02 | leedm777 | Corydon76-home: no, I'm just slow at typing :-D |
| 17:17.47 | Corydon76-home | That is, you have v1 in Asterisk 12, you've already incremented to v2 for Asterisk 13, and now a security issue comes up, where you have to drop a feature in v1. |
| 17:18.33 | Corydon76-home | So Asterisk 12 gets v3, but certain features exist in v2 which don't exist in v3. |
| 17:18.56 | Corydon76-home | Now you have a definite need for feature flags to determine what version you have. |
| 17:19.08 | leedm777 | Okay, I see where you're coming from. |
| 17:19.25 | coreyf1513 | also if you drop the hackme feature from v1 then /ari/v1/asterisk/hackme is entirely invalid. incrementing the version number would only break everything else (that was not effected) |
| 17:19.57 | Corydon76-home | Worse yet, any application developer MUST at that point hurry up and create a new release, in order to work with the new Asterisk 12 security fixed release |
| 17:20.05 | pabelanger | but to you really need to drop /ari/v1/asterisk/hackme? Why not keep the function name, and generate a 404 or an exception message |
| 17:20.19 | pabelanger | then the v1 could still exist |
| 17:20.32 | leedm777 | pabelanger: good answer! |
| 17:20.36 | Corydon76-home | pabelanger: I think that's absolutely what would need to occur |
| 17:20.59 | Corydon76-home | But you don't want to force developers to have to change their api versions |
| 17:21.05 | leedm777 | Probably a 501 or 410, with specific text saying that the function was removed. |
| 17:21.08 | pabelanger | correct |
| 17:21.28 | Corydon76-home | Leave v1 alone and let those functions continue to exist, because it remains a STABLE api |
| 17:22.41 | leedm777 | Okay, that sounds like a good plan. Let me go over it to see if everyone's on the same page. |
| 17:22.47 | pabelanger | Ya, I cann't think of a reason really to remove something once the api is stable. But changing the return value / http status code is acceptable |
| 17:23.15 | leedm777 | So we have /ari/v1/asterisk/hackme, which persists on into /ari/v2/asterisk/hackme. |
| 17:23.37 | Corydon76-home | No, you can remove apis on v2, because it's a new API |
| 17:23.52 | Corydon76-home | But v1 continues to exist; it just doesn't do anything |
| 17:24.14 | leedm777 | For security reasons, we decide we need to remove that functionality from all versions. The function is removed from /ari/v3, but calls to that resource in /ari/v1 and /ari/v2 respond with 410 Gone. |
| 17:24.18 | Corydon76-home | Or you could change the parameters in v2 |
| 17:24.44 | leedm777 | assuming that both v1 and v2 have been released and are finalized |
| 17:25.08 | Corydon76-home | Yes, assuming they're both released and finalized, they'd both return 410 Gone |
| 17:25.25 | Corydon76-home | But it'd be gone in the next release |
| 17:25.34 | pabelanger | Yup, and properly notify developers and everybody is happy |
| 17:25.45 | leedm777 | Yup. |
| 17:25.49 | pabelanger | <PROTECTED> |
| 17:25.57 | Qwell | everybody except the hackers. :( |
| 17:26.39 | Corydon76-home | Well, it's not actually purged in trunk, because the api has to remain stable across versions |
| 17:26.54 | Corydon76-home | It just won't exist for the next version of the api |
| 17:27.05 | leedm777 | agrees with Corydon76-home |
| 17:27.24 | Corydon76-home | That's why you have to say that it won't exist in v3, instead of saying that it is purged from trunk |
| 17:27.25 | pabelanger | Corydon76-home: right |
| 17:27.36 | pabelanger | nods |
| 17:27.37 | *** join/#asterisk-dev [TK]D-Fender (~chatzilla@64.235.216.2) |
| 17:27.54 | pabelanger | Ya, ideally we don't have a new rest API with each new asterisk release |
| 17:31.01 | Corydon76-home | That's why it's better if the function doesn't change, that you leave the version number alone for functions which don't change |
| 17:31.39 | Corydon76-home | and ONLY increment the version number for functions which need changed parameters and/or results |
| 17:32.28 | Corydon76-home | You have to think about external application life cycle, not just think about "what's easiest for a new developer" |
| 17:33.23 | leedm777 | still doesn't get it. |
| 17:33.29 | Corydon76-home | Remember that your long-running developers are your best customers |
| 17:33.55 | coreyf1513 | Corydon76-home: are you talking about having each function have a version number, no version number for the api as a whole? |
| 17:33.59 | leedm777 | Corydon76-home: agreed, but I think versioning each function individually would drive them into madness. |
| 17:34.25 | Corydon76-home | Not forcing them to update the api names (which includes the version number) every time you bump the version means that they can continue to work fine and NOT have to change modules that don't otherwise change |
| 17:34.43 | Corydon76-home | coreyf1513: that's essentially the way it works, yes |
| 17:35.42 | leedm777 | Corydon76-home: we wouldn't be forcing them to. They can mix usage of /v1 and /v2, so long as both are supported on that version of Asterisk. |
| 17:35.56 | leedm777 | whether or not the same function is presented in both versions of the API. |
| 17:36.21 | coreyf1513 | Corydon76-home: that would be great, less stable functions would not bump the version number of stable functions. |
| 17:36.23 | leedm777 | At some point /v1 probably goes away, at which point they will have to upgrade. But that's the normal cycle of technology. |
| 17:37.10 | pabelanger | we should atleast discuss what that lifetime is going to be? |
| 17:37.13 | Corydon76-home | leedm777: You need to put yourself in the shoes of an external application developer to understand |
| 17:38.32 | leedm777 | Corydon76-home: I'm trying to, but I still don't see how versioning individual functions makes their lives anything other than a nightmare. |
| 17:38.59 | Corydon76-home | Think about it this way. When glibc adds new functionality, do you want to change Asterisk across all libc functions to get the newest API, or would you prefer to assume that existing applications will continue to work as before? |
| 17:40.43 | Corydon76-home | So you need to either commit to NEVER removing existing APIs, or you should simply only increment versions for functions which need to be incremented |
| 17:40.44 | leedm777 | Corydon76-home: the old API continues to work. they can switch to the new one however they see fit. |
| 17:41.02 | Corydon76-home | leedm777: not true. You've said you want to remove v1 at some point |
| 17:41.21 | leedm777 | Corydon76-home: yes. nothing lives forever. |
| 17:41.52 | Corydon76-home | Look at glibc. The GLIBC_2_2 still exists in GLIBC_2_13 |
| 17:41.53 | pabelanger | actually, I thought we decided to only deprecate stuff in asterisk, not remove it. Is that changing? |
| 17:42.40 | Corydon76-home | If you want to use the version of APIs that GLIBC 2.2 provided, you can absolutely do so, even if glibc 2.13 is installed |
| 17:43.22 | pabelanger | forcing users to upgrade has been problematic in the past with asterisk |
| 17:43.22 | pabelanger | EG: CLI change |
| 17:43.35 | Corydon76-home | When you're talking link libraries, they have less of a choice, since versions have to be at library level |
| 17:44.12 | Corydon76-home | But if you look at other RESTful APIs, they tend to only bump version numbers of functions that need their parameters or result values to change |
| 17:45.45 | Corydon76-home | Have to go, I have a disk issue on a production database |
| 17:49.07 | leedm777 | Okay, I'll start writing up some notes on the wiki (https://wiki.asterisk.org/wiki/x/WwCUAQ). |
| 18:13.08 | Marquis42 | leedm777: s/tenants/tenets :) But I think I'm leaning towards Corydon76-home's idea from other RESTful APIs where functions are indvidually versioned. Obviously it puts burden on the Asterisk developers to make that right, but as an ARI user it makes it reasonably easy for me to have a "manifest" of used functions and their versions to check against for compatibility. Just my two cents. |
| 18:15.19 | leedm777 | Marquis42: hm. I still don't get it. Let's say that there's /ari/v1/really/stable/function, and /ari/v42/something/new/and/shiny, plus 40 variations of stuff in between. You'd rather want to know that /really/stable/function was back in the /v1 namespace instead of just having /ari/v42/really/stable/function just do the same thing? |
| 18:19.39 | Marquis42 | I'd rather be able to pull a JSON document that tells me what functions are part of a REST API's major version(s) and be able to check against individual ones for minor version bumps. |
| 18:31.20 | coreyf1513 | leedm777: if I program something for /ari/v1/really/stable/function, the existence of /ari/v42/something/new/and/shiny should not require my old stable application to know about v42 |
| 18:31.50 | leedm777 | coreyf1513: exactly, so long as the /v1 API is still supported. |
| 18:34.28 | Corydon76-home | leedm777: create the tables of lookups so that you have 42 versions of exactly the same api. Then look at the table of lookups where you only bump the version number of the function which changed (at which point, you're unlikely to get past v3 for any arbitrary function). Then tell me which one seems more maintainable to you |
| 18:37.40 | Corydon76-home | Here's another way to think about it. You're looking at the string and seeing a version number that gets incremented, but you need to look at it another way, which is that the api is simply an arbitrary string into a table of lookups. Same as, say, "snprintf". As an application developer, do you want the function names you call to be constant strings, or do you want them to be variadic expansions, depending upon the |
| 18:37.40 | Corydon76-home | destination to which you connect? |
| 18:38.33 | Corydon76-home | i.e. do you always want to be calling "snprintf", or do you want to be calling a function that you won't know what it's called until runtime? |
| 18:40.35 | Corydon76-home | Would you want to be calling "snprintf" or "glibc/v2_13/snprintf"? |
| 18:41.24 | leedm777 | Corydon76-home: It's a bit of a false comparison. Sharing object linking and RESTful API invocation are different beasts. |
| 18:42.02 | leedm777 | But I would rather be able pick a version of the API, and code my application to that API, and not worry about the versions of individual functions. |
| 18:42.19 | Corydon76-home | Yes, they certainly are, but when you're dealing with function versioning, you don't want 34 versions of exactly the same beast |
| 18:42.26 | leedm777 | When it comes to maintaing the functions, I can look at the diffs between API versions to see what has changed between them. |
| 18:42.49 | leedm777 | Corydon76-home: there are 34 names for the same beast. |
| 18:42.59 | Corydon76-home | leedm777: How many times have you looked at the diff between glibc 2.4 and glibc 2.13, honestly? |
| 18:43.08 | leedm777 | Like I said, different world. |
| 18:43.44 | Corydon76-home | Absolutely, different world for you, because you're on one side for glibc and on the opposite side for the ari api |
| 18:44.06 | Corydon76-home | You need to put yourself on the other side of the RESTful api to understand |
| 18:44.46 | Corydon76-home | Hey, Digium has a graphical client team inhouse, right? |
| 18:45.27 | leedm777 | Not sure what you mean by that. |
| 18:45.33 | Corydon76-home | Switchvox? |
| 18:46.06 | leedm777 | They're not in-house. |
| 18:46.38 | Corydon76-home | They'll be consumers of the ari API, won't they? |
| 18:46.47 | leedm777 | Yup. |
| 18:46.59 | Corydon76-home | Have you had this discussion with them? |
| 18:47.15 | leedm777 | Nope; no versioning discussion. |
| 18:47.29 | Corydon76-home | I think that discussion needs to occur. |
| 18:48.06 | Corydon76-home | I suspect they're going to tell you the same thing as I am, but talk to them about it. |
| 18:48.57 | leedm777 | Sure. Could either Corydon76-home or Marquis42 point me to another RESTful API that versions functions individually? Just so I have a point of reference? |
| 18:53.32 | Corydon76-home | I'd guess Marquis42 has some examples off the top of his head. I tend not to use them in my particular practice |
| 18:53.49 | Corydon76-home | Tend not to use RESTful apis at all, that is |
| 19:12.11 | *** join/#asterisk-dev vlad_starkov (~vlad_star@109.188.124.140) |
| 19:16.15 | Juggie | yeah rest... sigh ;) |
| 19:16.26 | Juggie | buzword way of saying http |
| 19:18.17 | Juggie | id disagree on a version # per function though |
| 19:18.26 | Corydon76-home | Juggie: RESTful is talking about a particular way of using HTTP as a medium, though |
| 19:18.47 | Juggie | yeah.. but its still putting lipstick on a pig |
| 19:19.23 | Corydon76-home | Unfortunately, "Internet" has become a buzzword for the "web" |
| 19:19.31 | Juggie | id argue one version number for ari, not a version per function |
| 19:19.52 | Corydon76-home | That doesn't mean that the Internet doesn't have more services than just the web |
| 19:19.59 | Juggie | correct. |
| 19:20.16 | Juggie | haing one function be at v1 and the other be at v10 is dumb |
| 19:20.17 | Corydon76-home | Juggie: how often do you use RESTful APIs? |
| 19:20.38 | Juggie | often enough |
| 19:21.11 | Corydon76-home | Juggie: how often do you maintain applications that use RESTful APIs? |
| 19:21.25 | Juggie | infrequently |
| 19:22.02 | Juggie | but i'm just approaching it from a protocol perspectie, different version numbers per function would be a nightmare to work with. |
| 19:22.16 | Corydon76-home | As long as v1 hangs around forever, I'm fine with Asterisk incrementing the entire version. |
| 19:22.18 | Juggie | i'd argue to keep one api version number, like a svn revision number. |
| 19:22.38 | Juggie | so, ari/v1/originatecall may only change in v1 and v10 |
| 19:22.44 | Juggie | but you can call it with v5 v8 etc |
| 19:22.47 | Juggie | and get v1 version |
| 19:23.02 | Corydon76-home | That's what leedm777 is advocating, yes |
| 19:23.15 | Juggie | right. that makes sense treat it like a pointer in time. |
| 19:23.23 | Juggie | as opposed to knowing one function is v1 and one is v10 etc |
| 19:24.03 | Corydon76-home | But you're reading the string out and thinking "sense", instead of looking at the string and thinking "this is the string I need to use" |
| 19:24.35 | Juggie | i dont understand what you are getting at |
| 19:24.35 | Corydon76-home | Most people don't care about the internals of that string, and only want "constant string to use to get X functionality" |
| 19:25.33 | Corydon76-home | You're thinking about the internals of that string, when in fact, it only ever needs to be make sense to the developers, not to the consumers of the api |
| 19:26.20 | Juggie | right.. i was arguing from a developer point of view it was needlessly convoluted. |
| 19:26.52 | Corydon76-home | I'm arguing from the perspective of a consumer of that API, which is also a developer, but on the other side of it |
| 19:27.13 | Juggie | i suppose... we will not agree i am sure and i see where you are coming from :) |
| 19:29.45 | *** join/#asterisk-dev oej (~oej@scandic806.host.songnetworks.se) |
| 19:29.46 | *** mode/#asterisk-dev [+o oej] by ChanServ |
| 20:27.34 | *** join/#asterisk-dev oej (~oej@scandic806.host.songnetworks.se) |
| 20:27.34 | *** mode/#asterisk-dev [+o oej] by ChanServ |
| 20:38.10 | *** join/#asterisk-dev pabelanger (~pabelange@asterisk/contributor-and-bug-marshal/pabelanger) |
| 20:38.10 | *** mode/#asterisk-dev [+o pabelanger] by ChanServ |
| 20:50.47 | *** join/#asterisk-dev vlad_starkov (~vlad_star@109.188.124.229) |
| 20:50.50 | *** join/#asterisk-dev malcolmd (~malcolmd@pdpc/sponsor/digium/malcolmd) |
| 20:50.50 | *** mode/#asterisk-dev [+o malcolmd] by ChanServ |
| 23:40.05 | *** join/#asterisk-dev serafie (~erin@user-24-214-173-250.knology.net) |
| 23:52.15 | *** join/#asterisk-dev vlad_starkov (~vlad_star@109.188.127.75) |