On Thu, Apr 28, 2016 at 3:16 PM, Dilshan Edirisuriya <ed.dils...@gmail.com> wrote:
> Hi Prabath, > > Just commenting by looking at the EMM/IOT current state (I do agree that > there needs to be a proper standard on this). Although contract first > approach looks far more clean, EMM/IOT already have APIs defined. Hence > going with contract first approach could result in slight modifications to > the APIs? Not sure whether its valid though. If it so when it comes to EMM > case if there are customers using it, it could have an impact. > Well, when APIs evolve and new functionalities are introduced, it's inevitable that we come across API changes. However, as with pretty much any other API, these changes cannot be done overnight. In other words, irrespective of the fact that what forced them, such changes need to be integrated gradually through a process that allows us to first announce the change, then deprecate the relevant resource definitions and finally delete them. So, while agreeing there's an impact, that can be avoided as explained above, and thus, can be thought of as a less concerning factor at this point. > Also why do we see different standards across different products like AppM > and EMM? Naming conventions etc. are slightly different. Also how do you > manage to version the APIs with this? In AppM I see a version available in > URL path. Correct me if I am wrong. > If you carefully read the contents, this is what's meant to be discussed here in the thread. That is, to push for just one approach, to avoid folks using different methodologies across the platform to do the same things. Cheers, Prabath > > Regards, > > Dilshan > > On 28 April 2016 at 14:53, Prabath Abeysekera <praba...@wso2.com> wrote: > >> Hi Everyone, >> >> What I'm trying to do primarily is setting up Swagger-based docs for >> EMM/IoTS related APIs. However, while I was looking deeper into this, came >> across a few things that I need clarifications upon. >> >> *Code-first or Contract-first?* >> >> Right now it appears that there are two approaches being used in the >> platform for API design and development. >> >> 1. Contract first approach, which utilizes composing the Swagger >> definition upfront and then generating the API implementation out of it. >> >> (** I do understand that there's a whole big debate around different >> developer communities as to whether REST needs a contract, except for the >> HTTP protocol, at all. But, the primary intention of this thread is "not" >> to jump into a similar argument :) ) >> >> 2. Code first approach, which utilizes implementing the API first and >> then generates Swagger definition to be used for documentation purposes, >> etc. >> >> Each approach obviously has its own pros and cons. This is, therefore, to >> see what needs to be/already have standardized as the best approach to go >> about API design and implementation. >> >> If we consider contract-first approach, that looks more elegant and lets >> us enable enforcing proper governance across the API design and >> implementation process. For instance, folks can first work on the Swagger >> definition as the contract, at the design phase and then go into the >> implementations later on after verifying the resource definitions, etc. The >> second approach, on the other hand, makes it easier for us to deal with in >> terms of implementing complex and more coarse-grained HTTP APIs (which I >> believe is a common-case in the platform?) and exposing their definitions. >> >> *Impact of this on API documentation* >> >> So, coming back to the topic of documenting APIs with what was discussed >> earlier, if we go by the first approach, there we have the swagger >> definition up-front so we wouldn't need to go for any annotation-based >> models, etc and instead, can directly generate API documentation based on >> the existing Swagger definition via an appropriate doc generator tool. >> >> In contrast, the code-first approach demands us to go for an >> annotation-model or something similar to get the documentation done. >> >> Whichever the case would ultimately produce the same output, but I >> thought, as a platform we need to stick to just one approach and document >> it properly. So the question is, what would that be? >> >> >> Cheers, >> Prabath >> -- >> Prabath Abeysekara >> Technical Lead >> WSO2 Inc. >> Email: praba...@wso2.com >> Mobile: +94774171471 >> >> _______________________________________________ >> Architecture mailing list >> Architecture@wso2.org >> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture >> >> > -- Prabath Abeysekara Technical Lead WSO2 Inc. Email: praba...@wso2.com Mobile: +94774171471
_______________________________________________ Architecture mailing list Architecture@wso2.org https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
