Hi all! I think we may try to solve too many things at the same time in this discussion. But also in our API. It just seems things are a bit too tightly coupled.
For example: *We can't change/update REST methods, cause they affect SOAP calls. Currently we have a just a single class that does both* => It was easy when the API was simple. But then over time it actually became harder, cause we discovered that under the covers Soap and Rest representation is different. *We introduced REST 10years ago and the definitions of REST changed over time* => We created the OpenMeetings REST API over 10years(!!) ago. At that time the definition of REST was quite fluent. By now there is quite a different and more strict understanding of what Rest means. And how HTTP methods (GET/POST/PUT/DELETE), resource paths ( having nouns not verbs as resource paths, eg: /users/$identifier), using the right kind of request/response message structure or for example how authentication/security works. Things have changed. And I actually think by now it is taking more time and effort to try to get Soap/Rest into 1 class. Then separating them. As well as it's just maybe a long time since we had a major uplift. How about we do the following: 1) We keep the current SOAP/REST API structure as is => Minimise rework / No breaking changes => We accept some minor quirks around some *documentation only* annotations in order to document it in a way people can use it 2) For v7.0.0 or v8.0.0 we introduce a v2 of the Rest API But: => v2 is REST only. The existing/v1 API is the SOAP/REST API. And SOAP stays where it is. That way we have less work in trying to make 2 things into 1. => Soap and Rest can still use the same "adapter" class in order to achieve 'feature parity'. But we do _not_ attempt for example that method parameters need to match => Having a single v2 REST only interface makes it also easier to write integration tests. Cause you only need to test the REST interface. => There isn't really any issue with the SOAP interface. SOAP hasn't changed in the last 10years. There isn't any need to go for a v2 in the SOAP API 3) We agree _before_ adding a v2 what REST "guidelines" we adopt => Instead of arguing what kind of HTTP method, security headers, POST body parameters we adopt a guideline/standard document. And simply comply with that standard. => This will also make it a lot easier to: A) Integrate with it, cause people are used to the format/standard/guidelines and there is less discussion needed B) The tooling will be much easier, because all the code generators, documentation tools, CXF-RS, json-mappers we are using are referencing a similar or same guidelines/standard. So we not constantly need to customise things to fit into how the existing OpenMeetings API works An example of a REST guideline/standard that we could adopt is: OpenAPI 3.0.x (https://swagger.io/specification/) + Restful recommendations ( https://restfulapi.net/) @Maxim Solodovnik <solomax...@gmail.com> what do you think? I think more than 10years is enough for a single version of an API. I think by now it actually is _less_ work to have a new v2 Rest only version of the API then trying to somehow create a SOAP/REST API and try to enhance that into a "RESTful" way but not break it at the same time. Thanks, Seb Sebastian Wagner Director Arrakeen Solutions, OM-Hosting.com http://arrakeen-solutions.co.nz/ https://om-hosting.com - Cloud & Server Hosting for HTML5 Video-Conferencing OpenMeetings <https://www.youracclaim.com/badges/da4e8828-743d-4968-af6f-49033f10d60a/public_url> <https://www.youracclaim.com/badges/b7e709c6-aa87-4b02-9faf-099038475e36/public_url> On Thu, 23 Sept 2021 at 02:24, Daniel Baker <i...@collisiondetection.biz> wrote: > Can you not employ an extra programmer? > On 22/09/2021 13:24, Maxim Solodovnik wrote: > > > > On Wed, 22 Sept 2021 at 19:20, Ali Alhaidary <ali.alhaid...@the5stars.org> > wrote: > >> >> On 9/22/21 3:14 PM, Maxim Solodovnik wrote: >> >> I only can do manual testing here :( >> >> What is manual testing? >> > > I'm installing everything > setting up integration and do clicking :))) > > >> IMO these changes (if we will be able to do them) worth to be done >> >> what is IMO ? >> > > In My Opinion :) > >> Why I raise some old design issues: we can do changes now and let the API >> unchanged for another several years :))) >> >> What is several years ;-) >> > > Well I believe REST API was changed 2-3 times, so we are trying to keep it > stable > v1/v2 etc. approach can also be applied > the problem here: I don't have enough time to maintain more than one > version :(( > > >> On Wed, 22 Sept 2021 at 19:09, Ali Alhaidary <ali.alhaid...@the5stars.org> >> wrote: >> >>> The issue here is that, It is a lot of work, and, a lot of testing that >>> follows. We are not a direct API users, however, moodle plugin is. Along >>> the road, things could break in such change. So, if you see this change is >>> the the way forward, I am in with as usual a dedicated production server >>> for selected teaches/students as long as the old work (mainly recordings) >>> is not lost, and, only one environment is used (as is now), i.e. moodle >>> plugin can handle all the communication. >>> >>> The issue is being discussed by only three people, how many others are >>> using these APIs ? How many apps are up and running on them now ? looking >>> at the moodle plugin downloads, >>> https://moodle.org/plugins/mod_openmeetings/stats there is a peak >>> during the past year, and I am sure the case is the same with other LMS and >>> custom built apps, keeping in mind that OM can work exceptional good by >>> itself. >>> >>> Ali >>> >>> >>> On 9/22/21 2:16 PM, Maxim Solodovnik wrote: >>> >>> These changes are only being discussed >>> Nothing is broken, yet :)))) >>> we can @Deprecate these old methods and/or move it to some prefixed URL >>> so API users will need to change base URL from >>> https://localhost:5443/openmeetings to >>> https://localhost:5443/openmeetings/v1 >>> >>> On Wed, 22 Sept 2021 at 13:14, seba.wag...@gmail.com < >>> seba.wag...@gmail.com> wrote: >>> >>>> @Ali Alhaidary <ali.alhaid...@the5stars.org> >>>> The other alternative to fix the issue AND make it backwards compatible >>>> would be to have a /v2 version of the API >>>> >>>> So all endpoints would be duplicated to have version /v2 of the API >>>> (with maybe some other fixes) >>>> and the current API stays the same. But would not receive any >>>> improvements anymore/deprecated. >>>> >>>> But that would be quite a bit of work. But yeah, that is what people do >>>> when they want to avoid breaking changes. Need to do versioning. >>>> >>>> Thanks >>>> Seb >>>> >>>> >>>> Sebastian Wagner >>>> Director Arrakeen Solutions, OM-Hosting.com >>>> http://arrakeen-solutions.co.nz/ >>>> https://om-hosting.com - Cloud & Server Hosting for HTML5 >>>> Video-Conferencing OpenMeetings >>>> >>>> <https://www.youracclaim.com/badges/da4e8828-743d-4968-af6f-49033f10d60a/public_url> >>>> <https://www.youracclaim.com/badges/b7e709c6-aa87-4b02-9faf-099038475e36/public_url> >>>> >>>> >>>> On Wed, 22 Sept 2021 at 18:10, Ali Alhaidary < >>>> ali.alhaid...@the5stars.org> wrote: >>>> >>>>> We are using OM in production with moodle front end, we can not >>>>> tolerate downtime neither with OM or its plugin (that needs fixing, but >>>>> living with), and to tell you the truth, I do not see it as 'broken' from >>>>> that angle. >>>>> >>>>> So my answer is B. >>>>> >>>>> Ali >>>>> On 9/22/21 2:10 AM, seba.wag...@gmail.com wrote: >>>>> >>>>> It is broken. The problem is the fix will be a breaking change that >>>>> will require 3rd party integration code to be fixed. Not a big fix, but a >>>>> fix. Eg the Moodle Plugin requires some minor changes. >>>>> >>>>> The workaround is to write some additional wrapper code to make it >>>>> backwards compatible. Which is also a bit confusing. >>>>> >>>>> I also don't understand quite if you answer is pro or contra changing >>>>> the response. >>>>> >>>>> So is your statement: >>>>> A) Yes, lets fix it to align our JSON response with what the >>>>> schema/method signature says. We don't like wrapper objects. And I am >>>>> happy >>>>> that people have to change their integration code to use newer versions of >>>>> OpenMeetings. >>>>> B) No, lets leave it like this for now and we do whatever other >>>>> additional code we need to write to workaround so that our documentation >>>>> and schema matches what the actual API responses look like >>>>> >>>>> If you could please clarify if you are A, B. Or if you don't mind >>>>> either way/no strong opinion :) >>>>> >>>>> Thanks >>>>> Seb >>>>> >>>>> >>>>> Sebastian Wagner >>>>> Director Arrakeen Solutions, OM-Hosting.com >>>>> http://arrakeen-solutions.co.nz/ >>>>> https://om-hosting.com - Cloud & Server Hosting for HTML5 >>>>> Video-Conferencing OpenMeetings >>>>> >>>>> <https://www.youracclaim.com/badges/da4e8828-743d-4968-af6f-49033f10d60a/public_url> >>>>> <https://www.youracclaim.com/badges/b7e709c6-aa87-4b02-9faf-099038475e36/public_url> >>>>> >>>>> >>>>> On Wed, 22 Sept 2021 at 10:59, Ali Alhaidary < >>>>> ali.alhaid...@the5stars.org> wrote: >>>>> >>>>>> Hi, >>>>>> >>>>>> We have an old saying 'If it is not broken, do not fix it' ;-) >>>>>> >>>>>> Ali >>>>>> On 9/22/21 12:46 AM, seba.wag...@gmail.com wrote: >>>>>> >>>>>> Hi, >>>>>> >>>>>> as discussed in the comments section in >>>>>> https://github.com/apache/openmeetings/commit/4daf7c1f53738cd786dc976114cc5278b4f05f4f#comments >>>>>> >>>>>> >>>>>> we would like to propose a breaking change for the OpenMeetings >>>>>> Json/Rest API in v7.0.0 >>>>>> >>>>>> Problem: JSON response wrapping >>>>>> Currently CXF-RS is configured to wrap the JSON response into another >>>>>> object. >>>>>> >>>>>> Example: Method signature: public List<AppointmentDTO> range(...) { >>>>>> ... } (Example taken from >>>>>> https://github.com/apache/openmeetings/blob/master/openmeetings-webservice/src/main/java/org/apache/openmeetings/webservice/CalendarWebService.java#L111 >>>>>> ) >>>>>> >>>>>> OLD/CURRENT JSON Response: >>>>>> { >>>>>> "appointmentDTO": >>>>>> [ >>>>>> { >>>>>> itemXYZ: 123, ... >>>>>> } >>>>>> ] >>>>>> } >>>>>> >>>>>> >>>>>> Proposed NEW/UPDATED JSON Response: >>>>>> // no wrapping object around it, just return list >>>>>> [ >>>>>> { >>>>>> itemXYZ: 123, ... >>>>>> } >>>>>> ] >>>>>> >>>>>> Reasoning: The wrapping "{ "appointmentDTO": ... }" should be >>>>>> dropped from the json response body. "appointmentDTO" is generated but it >>>>>> is not in any schema definition or method signature. Cause there is >>>>>> nothing >>>>>> in the method signature that would tell anybody where " "appointmentDTO": >>>>>> [" is coming from. Other than by testing the API call and finding out by >>>>>> try and error. >>>>>> >>>>>> CXF-RS allows configuring our Web Service to NOT generate that >>>>>> wrapping element. And turn this behaviour off and just generate the list. >>>>>> See "dropRootName" in the CXF docs at: >>>>>> >>>>>> https://cxf.apache.org/docs/jax-rs-data-bindings.html#JAXRSDataBindings-WrappingandUnwrappingJSONsequences >>>>>> >>>>>> *This affects all methods returning a JSON response body (which is >>>>>> pretty much every API Method)* >>>>>> >>>>>> Please reply to this email if you have concerns, questions or >>>>>> objections. >>>>>> >>>>>> Thanks! >>>>>> Seb >>>>>> >>>>>> Sebastian Wagner >>>>>> Director Arrakeen Solutions, OM-Hosting.com >>>>>> http://arrakeen-solutions.co.nz/ >>>>>> https://om-hosting.com - Cloud & Server Hosting for HTML5 >>>>>> Video-Conferencing OpenMeetings >>>>>> >>>>>> <https://www.youracclaim.com/badges/da4e8828-743d-4968-af6f-49033f10d60a/public_url> >>>>>> <https://www.youracclaim.com/badges/b7e709c6-aa87-4b02-9faf-099038475e36/public_url> >>>>>> >>>>>> >>> >>> -- >>> Best regards, >>> Maxim >>> >>> >> >> -- >> Best regards, >> Maxim >> >> > > -- > Best regards, > Maxim > >
