coffee

Generating Documentation and Modifying the sTeam-REST API

(ˢᵒᶜⁱᵉᵗʸserver) aims to be a platform for developing collaborative applications. sTeam server project repository: sTeam. sTeam-REST API repository: sTeam-REST Documentation Documentation is an important part of software engineering. Types of documentation include: Requirements - Statements that identify attributes, capabilities, characteristics, or qualities of a system. This is the foundation for what will be or has been implemented. Architecture/Design - Overview of software. Includes relations to an environment and construction principles to be used in design of software components. Technical - Documentation of code, algorithms, interfaces, and APIs. End user - Manuals for the end-user, system administrators and support staff. Marketing - How to market the product and analysis of the market demand. Doxygen Doxygen is the de facto standard tool for generating documentation from annotated C++ sources, but it also supports other popular programming languages such as C, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOffice flavors), Fortran, VHDL, Tcl, and to some extent D. The Doxygen treats files of other languages as C/C++ and creates documentation for it accordingly. sTeam documentation was tried to be created with the doxygen. But empty documentation was created due to the lack of the doxygen annotations used in the project.  Doxygen doc generation. Doxygen Docs The next way to create documentation was to make use of the autodoc utility provided by the Pike. The utility to generate docs was provided in the later versions of the Pike(>=8.0.155). The autodoc files are generated and  later these are converted into  html pages. The commands used for generating the autodoc include:- pike -x extract_autodoc /source pike -x autodoc_to_html /src /opfile The autodoc_to_html utility converts a single autodoc file to an html page. As a result a shell script was written to convert all the generated autodoc files to the html file. docGenerator.sh #!/bin/bash shopt -s globstar for filename in ./**/*.pike.xml; do outputFile=doc/${filename#./} outputFile=${outputFile%.xml}."html" if [ -d $(dirname "./"$outputFile) ]; then touch "./"$outputFile else mkdir -p $(dirname "./"$outputFile) && touch "./"$outputFile fi pike -x autodoc_to_html $filename "./"$outputFile done Autodoc Documentation The documentation generated by this was less informative and lacked the referrals to other classes and headers. The societyserver project was developed long back but the autodoc utility was introduced in the later versions of pike. As a result the source files lacked the autodoc tags which are required to generate a well informative documentation with bindings to other files. Restructuring the sTeam-REST API The sTeam-REST API project made use of the angular-seed to initiate the development during the early phases. However these files still existed in the project. This had lead to a pandemonium and created difficulty in understanding the project. The files had to be removed and the app was in dire need of a restructuring. The following issues have been reported and resolved. Issue. Github Issue Github PR sTeam-REST Issues Issues PR The new UI can be seen below. Home Register About Testing the REST API The functionality to run the tests using the npm test command was added to the project.…

Continue ReadingGenerating Documentation and Modifying the sTeam-REST API

sTeam REST API

(ˢᵒᶜⁱᵉᵗʸserver) aims to be a platform for developing collaborative applications. sTeam server project repository: sTeam. sTeam-REST API repository: sTeam-REST REST Services REST is the software architectural style of the World Wide Web. REST (Representational State Transfer) was introduced by Roy Fielding in his doctoral dissertation in 2000. Its purpose is to induce performance, scalability, simplicity, modifiability, visibility, portability, and reliability.It has client/server relationship with a uniform interface and is stateless. REST is most commonly associated with HTTP but it is not strictly related to it. REST Principles Resources : Each and every component is a resource.A resource is accessed by a common interface using HTTP standard methods. Messages use HTTP methods like GET, POST, PUT, and DELETE. Resource identification through URI: Resources are identified using URI. Resources are represented using JSON or XML. Stateless interactions take place between the server and the client. No context is saved for the requests at the server.The client maintains the state of the session. HTTP methods The CRUD(create, retrieve, update and delete ) operations are performed using the HTTP methods. GET It is used to retrieve information. GET requests executed any number of times with the same parameters, the results would not change. This makes it idempotent. Partial or conditional requests can be sent. It is a read only type of operation. Retrieve a list of users: GET /api.example.com/UserService/users POST POST is usually used to create a new entity. It can also be used to update an existing entity. The request will have to do something with the entity provided in the URI. Create a new user with an ID 2: POST /api.example.com/UserService/users/2 PUT PUT request is always idempotent. Executing the same request any number of times will not change the output. PUT can be used to create or update an existing entity. Modify the user with an ID of 1: PUT /api.example.com/UserService/users/1 PATCH It is idempotent. PATCH requests only updates the specified fields of an entity. Modify a user with an id of 1: PATCH /api.example.com/UserService/users/1 DELETE It can be asynchronous or a long-running request. It removes the resource. It can be removed immediately or at a later instance of time. Delete a user with an ID of 1: DELETE /api.example.com/UserService/users/1  sTeam-REST API Installing and activating the REST API The REST API is developed as an application inside the sTeam server. This simplifies development quite a lot, as we don't need to restart the server for every change. Instead just the API code gets updated and reloaded. It may eventually be integrated into the core, however the longterm plan is actually to move functionality out of the core, to make development easier. To get the current version of the API clone the steam-rest repo into your home or to any place where you keep your development repos. Then change to the tools directory of your installation and run import-from-git. git clone https://github.com/societyserver/steam-rest cd steam-rest git checkout origin/rest.pike export steamrest=`pwd` cd /usr/local/lib/steam/tools ./import-from-git.pike -u root $steamrest / Note: The new import-from-git.pike script supports importing…

Continue ReadingsTeam REST API