Hi Natasha, Giving you a small suggestion to port the documentation to Swagger [1] as there are many advantages.
1. It is a well structured way of documenting APIs and it is used by many organizations. 2. Users of your API can use the swagger doc to generate clients. There are lots of tools that can do it for them including swagger-code-gen tool [2]. They supports many languages including HTML/javascript, Java. 3. Swagger doc can be used to generate server code skeleton. swagger-code-gen [2] includes that capability also. We used a customized version of it which is swagger2cxf-maven-plugin [3] to generate CXF server code when we were implementing the new REST API for API Manager. 4. Swagger doc can be used to generate HTML documentation too. Please note we are still in the process of doing it. Have a look at below links they are completely auto generated from Swagger docs, (Please ignore some characters like \n and * they should be corrected from the code generator. :) And we are yet to do some beatifications etc ) http://apidocs.wso2.com/rest/apim/store/v1/docs http://apidocs.wso2.com/rest/apim/publisher/v1/docs Please have a look at [4] and [5], what we have written for the REST API which might help you. You can use [6] as a tool for documenting. You might also have seen before an example of swagger-ui [7] which users can directly use the Swagger doc to invoke the API. Thanks, Malintha [1] http://swagger.io/specification/ [2] https://github.com/swagger-api/swagger-codegen [3] https://github.com/hevayo/swagger2cxf-maven-plugin [4] https://github.com/wso2/carbon-apimgt/blob/release-1.10.x/components/apimgt/org.wso2.carbon.apimgt.rest.api.store/src/main/resources/store-api.yaml [5] https://github.com/wso2/carbon-apimgt/blob/release-1.10.x/components/apimgt/org.wso2.carbon.apimgt.rest.api.publisher/src/main/resources/publisher-api.yaml [6] http://editor.swagger.io/ [7] http://petstore.swagger.io <http://petstore.swagger.io/>-- Malintha Amarasinghe Software Engineer *WSO2, Inc. - lean | enterprise | middleware* http://wso2.com/ Mobile : +94 712383306 On Fri, Dec 11, 2015 at 6:05 PM, Natasha Wijesekara <nata...@wso2.com> wrote: > I created a documentation jira and attached the api doc. > > Thanks > Natasha > > On Fri, Dec 11, 2015 at 4:23 PM, Nandika Jayawardana <nand...@wso2.com> > wrote: > >> Lets attach the doc to a documentation jira so that api is added to the >> documentation. >> >> Regards >> Nandika >> >> On Thu, Dec 10, 2015 at 7:03 PM, Natasha Wijesekara <nata...@wso2.com> >> wrote: >> >>> Hi, >>> >>> @Vinod, I used the format given in the Activiti rest api documentation >>> to include the response codes. >>> >>> @Nuwan, I have updated the user guide with the response codes and the >>> sample success responses. >>> >>> >>> Thanks, >>> Natasha >>> >>> On Thu, Dec 10, 2015 at 8:39 AM, Vinod Kavinda <vi...@wso2.com> wrote: >>> >>>> Hi Natasha, >>>> You can use the format used in Activiti rest api documentations [1] for >>>> this also. It includes response codes and sample success responses. >>>> >>>> @Dinithi, we are doing basic authentication using the security handler >>>> [2] AFAIK. >>>> >>>> [1] - http://www.activiti.org/userguide/#_get_a_deployment >>>> [2] - >>>> https://github.com/wso2/carbon-business-process/blob/master/components/bpmn/bpmn-rest/src/main/java/org/wso2/carbon/bpmn/rest/security/AuthenticationHandler.java >>>> >>>> Regards, >>>> Vinod Kavinda >>>> >>>> On Thu, Dec 10, 2015 at 7:30 AM, Dinithi De Silva <dinit...@wso2.com> >>>> wrote: >>>> >>>>> Hi Natasha, >>>>> >>>>> How are you going to ensure the security of the APIs? Have you thought >>>>> of using any security models? >>>>> >>>>> You can use permission/role based model in order to achieve this. >>>>> Just make sure which APIs need the administrative privileges. >>>>> >>>>> Thanks. >>>>> >>>>> >>>>> On Wed, Dec 9, 2015 at 9:30 PM, Nuwan Pallewela <nuw...@wso2.com> >>>>> wrote: >>>>> >>>>>> Hi Natasha, >>>>>> >>>>>> Great work. >>>>>> What happens if an invalid request or request with an illegal >>>>>> argument sent to the API ? >>>>>> It is better to have those response messages or response status code >>>>>> also in the documentation. >>>>>> >>>>>> Thanks, >>>>>> Nuwan >>>>>> >>>>>> On Wed, Dec 9, 2015 at 5:08 PM, Natasha Wijesekara <nata...@wso2.com> >>>>>> wrote: >>>>>> >>>>>>> Hi, >>>>>>> >>>>>>> I documented a user guide which contains details about the new rest >>>>>>> API implemented to generate the statistics for bpmn. >>>>>>> Appreciate any suggestions and comments. >>>>>>> >>>>>>> Thanks, >>>>>>> Natasha >>>>>>> >>>>>>> On Tue, Dec 8, 2015 at 4:44 PM, Vinod Kavinda <vi...@wso2.com> >>>>>>> wrote: >>>>>>> >>>>>>>> [Adding Architecture group] >>>>>>>> >>>>>>>> On Tue, Dec 8, 2015 at 2:45 PM, Natasha Wijesekara < >>>>>>>> nata...@wso2.com> wrote: >>>>>>>> >>>>>>>>> Hi , >>>>>>>>> >>>>>>>>> Currently the statistics generated for the bpmn-explorer is >>>>>>>>> generated using jaggery. When the work load is high, the >>>>>>>>> bpmn-explorer >>>>>>>>> takes a longer time to generate these statistics which causes >>>>>>>>> performance >>>>>>>>> issues. >>>>>>>>> >>>>>>>>> As a solution I am working a new stats REST api to generate these >>>>>>>>> statistics at the back-end. This reduces the work load and thereby >>>>>>>>> solves >>>>>>>>> the performance issues caused during peak times (when the workload is >>>>>>>>> at >>>>>>>>> its maximum). >>>>>>>>> >>>>>>>>> After taking in data about the bpmn processes, tasks and users >>>>>>>>> involved, the api processes these data into meaningful >>>>>>>>> statistics.These >>>>>>>>> statistics generated is used in the bpmn-explorer reporting dashboard >>>>>>>>> to >>>>>>>>> generate the statistical graphs. >>>>>>>>> >>>>>>>>> The statistics generated includes: >>>>>>>>> >>>>>>>>> 1) Average time duration for all completed processes. >>>>>>>>> The user has the option to either view all completed processes or >>>>>>>>> the top 10 processes which finished within a short time duration or >>>>>>>>> the top >>>>>>>>> 10 processes which took a long time duration to finish. >>>>>>>>> >>>>>>>>> 2) Average time duration of tasks of a completed process. >>>>>>>>> The user can select the completed process from the combo box and >>>>>>>>> view the average time duration. >>>>>>>>> >>>>>>>>> 3) User and the no. of tasks he/she has completed upto now. >>>>>>>>> >>>>>>>>> 4) Average time taken by each user to complete the tasks assigned >>>>>>>>> to him/her. >>>>>>>>> >>>>>>>>> 5) Task demand variation over time i.e. no. of tasks started and >>>>>>>>> no. of tasks completed in each month. This is useful for resource >>>>>>>>> allocation purposes. >>>>>>>>> >>>>>>>>> 6) Process demand variation over time i.e. no. of processes >>>>>>>>> started and no. of processes completed in each month regardless of a >>>>>>>>> specific user. This is useful for resource allocation purposes. >>>>>>>>> >>>>>>>>> 7) User Performance i.e. Task demand variation of users separately >>>>>>>>> over time i.e. no. of tasks started and no. of tasks completed in each >>>>>>>>> month. This is useful for resource allocation purposes. >>>>>>>>> >>>>>>>>> I have attached the class diagram of the REST api. The new stats >>>>>>>>> REST api will be integrated with the existing bpmn REST api. >>>>>>>>> Appreciate any suggestions and comments. >>>>>>>>> >>>>>>>>> Thanks, >>>>>>>>> -- >>>>>>>>> *Natasha Wijesekare* >>>>>>>>> >>>>>>>>> *Software Engineering Intern, WSO2 Inc: http://wso2.com >>>>>>>>> <http://wso2.com/>* >>>>>>>>> *email : nata...@wso2.com <nata...@wso2.com>* >>>>>>>>> *mobile: +94 771358651 <%2B94%20771358651>* >>>>>>>>> >>>>>>>> >>>>>>>> >>>>>>>> >>>>>>>> -- >>>>>>>> Vinod Kavinda >>>>>>>> Software Engineer >>>>>>>> *WSO2 Inc. - lean . enterprise . middleware <http://www.wso2.com>.* >>>>>>>> Mobile : +94 (0) 712 415544 >>>>>>>> Blog : http://soatechflicks.blogspot.com/ >>>>>>>> >>>>>>>> >>>>>>> >>>>>>> >>>>>>> -- >>>>>>> *Natasha Wijesekare* >>>>>>> >>>>>>> *Software Engineering Intern, WSO2 Inc: http://wso2.com >>>>>>> <http://wso2.com/>* >>>>>>> *email : nata...@wso2.com <nata...@wso2.com>* >>>>>>> *mobile: +94 771358651 <%2B94%20771358651>* >>>>>>> >>>>>>> _______________________________________________ >>>>>>> Dev mailing list >>>>>>> d...@wso2.org >>>>>>> http://wso2.org/cgi-bin/mailman/listinfo/dev >>>>>>> >>>>>>> >>>>>> >>>>>> >>>>>> -- >>>>>> ---------------------------------------------------------- >>>>>> >>>>>> *Nuwan Chamara Pallewela* >>>>>> >>>>>> >>>>>> *Software Engineer* >>>>>> >>>>>> *WSO2, Inc. *http://wso2.com >>>>>> *lean . enterprise . middleware* >>>>>> >>>>>> Email *nuw...@wso2.com <nuw...@wso2.com>* >>>>>> Mobile *+94719079739 <%2B94719079739>@* >>>>>> >>>>>> >>>>>> >>>>>> _______________________________________________ >>>>>> Architecture mailing list >>>>>> Architecture@wso2.org >>>>>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture >>>>>> >>>>>> >>>>> >>>>> >>>>> -- >>>>> *Dinithi De Silva* >>>>> Associate Software Engineer, WSO2 Inc. >>>>> m:+94716667655 | e:dinit...@wso2.com | w: www.wso2.com >>>>> | a: #20, Palm Grove, Colombo 03 >>>>> >>>>> _______________________________________________ >>>>> Dev mailing list >>>>> d...@wso2.org >>>>> http://wso2.org/cgi-bin/mailman/listinfo/dev >>>>> >>>>> >>>> >>>> >>>> -- >>>> Vinod Kavinda >>>> Software Engineer >>>> *WSO2 Inc. - lean . enterprise . middleware <http://www.wso2.com>.* >>>> Mobile : +94 (0) 712 415544 >>>> Blog : http://soatechflicks.blogspot.com/ >>>> >>>> >>>> _______________________________________________ >>>> Architecture mailing list >>>> Architecture@wso2.org >>>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture >>>> >>>> >>> >>> >>> -- >>> *Natasha Wijesekare* >>> >>> *Software Engineering Intern, WSO2 Inc: http://wso2.com >>> <http://wso2.com/>* >>> *email : nata...@wso2.com <nata...@wso2.com>* >>> *mobile: +94 771358651 <%2B94%20771358651>* >>> >> >> >> >> -- >> Nandika Jayawardana >> WSO2 Inc ; http://wso2.com >> lean.enterprise.middleware >> > > > > -- > *Natasha Wijesekare* > > *Software Engineering Intern, WSO2 Inc: http://wso2.com > <http://wso2.com/>* > *email : nata...@wso2.com <nata...@wso2.com>* > *mobile: +94 771358651 <%2B94%20771358651>* > > _______________________________________________ > Dev mailing list > d...@wso2.org > http://wso2.org/cgi-bin/mailman/listinfo/dev > > -- Malintha Amarasinghe Software Engineer *WSO2, Inc. - lean | enterprise | middleware* http://wso2.com/ Mobile : +94 712383306
_______________________________________________ Architecture mailing list Architecture@wso2.org https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
