Hi Prabath In the context of EMM/IoT product, we already have apis implemented, Now it is matter of documenting them with swagger. Given the fact that swagger has provided annotation based documenting strategy for already implemented apis, we can utilize them within EMM/IoT for documentation.
I am +1 for using the swagger annotations with apis, as it is easily manageable because contract is auto-generated by the underlying swagger libraries, Therefore we will not need to host api documentation separately as it is can be generated from the api implementation it self. This approach will make our effort easy for updating and maintaining apis since changes are reflected dynamically on the contract. Thanks Geeth *G. K. S. Munasinghe* *Senior Software Engineer,* *WSO2, Inc. http://wso2.com <http://wso2.com/> * *lean.enterprise.middleware.* email: [email protected] phone:(+94) 777911226 On Fri, Apr 29, 2016 at 10:56 AM, Lahiru Cooray <[email protected]> wrote: > Hi, > In AppM REST API developments we used Contract-first approach same as in > APIM (guideline [1]). > Since we did not have any REST API's we had to start from the scratch > (previously we had jaggery based API's and idea was to convert the logic > with proper REST naming conventions) > Contract-first approach helped us to do a proper designing before moving > to the implementation and easiness of generating client/server platform > independent stubs based on swagger annotations. > > But in EMM scenario as you already have the defined API's (which are > already been used) I think a better approach will be, generating the > swagger definition with an annotation model (for existing API's) and in > next phase/version you can continue with Contract-first approach with the > generated swagger def. > > [1] > http://wso2.com/library/tutorials/2016/03/tutorial-how-to-turn-a-cool-idea-into-a-business-api-with-the-wso2-platform/ > > On Thu, Apr 28, 2016 at 3:16 PM, Dilshan Edirisuriya <[email protected] > > 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. 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. >> >> Regards, >> >> Dilshan >> >> On 28 April 2016 at 14:53, Prabath Abeysekera <[email protected]> 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: [email protected] >>> Mobile: +94774171471 >>> >>> _______________________________________________ >>> Architecture mailing list >>> [email protected] >>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture >>> >>> >> >> _______________________________________________ >> Architecture mailing list >> [email protected] >> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture >> >> > > > -- > *Lahiru Cooray* > Software Engineer > WSO2, Inc.;http://wso2.com/ > lean.enterprise.middleware > > Mobile: +94 715 654154 > > _______________________________________________ > Architecture mailing list > [email protected] > https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture > >
_______________________________________________ Architecture mailing list [email protected] https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
