-
Notifications
You must be signed in to change notification settings - Fork 41
gsoc python library
GraphSpace is a web based platform that enables users to upload, interact and share their graphs. This platform is widely used and preferred by research groups to collaborate and work on their networks. The development of GraphSpace RESTful API has been a boon for users to easily upload and manage their graphs. The aim of this project is to implement a well designed, documented and tested Python package that allows users to interact with the GraphSpace RESTful API in their Python based applications.
In addition, there is a need of the documentation of the GraphSpace REST APIs themselves, which will provide a better understanding of the API specs. So the other part of this project involves documenting the GraphSpace REST APIs in RAML, generating HTML documentation from it and incorporating a test suite for the REST APIs.
The whole implementation of the project can be divided into four parts:
- Creating a Python library
- Creating core modules
- Implementing API methods
- Writing tests
- Creating documentation and configuring the package
- Writing documentation using Sphinx
- Configuring and uploading the package to PyPI
- Generating documentation for the REST APIs themselves
- Generating test suite for testing REST APIs documented in RAML
We will consider the yelp-python package as a reference for this project. The core module of our library implements the Client to the GraphSpace server. We will define methods for each endpoint in the Graphspace API which will take the required parameters and perform the HTTP request. We will make separate classes for each category of APIs, e.g., APIs related to graphs, groups, layout and tags. This design will help us in achieving modularity and better understanding of code. The entire code will be covered by tests to test the behaviour of each bit of functionality. We will use the ‘pytest’ framework for writing tests.
Maintaining documentation is an integral part of software development as it provides the details about how to use the software. After the completion of writing code for the package, we would start formulating the documentation for usage. Sphinx Python documentation library will be used for this purpose. The documentation will include the details regarding installation, importing, client instance initialization and the usage of the methods doing API calls.
The usefulness of the GraphSpace RESTful APIs mainly depends upon the fact that how well they are documented. Providing a detailed documentation on how to use the APIs like what are the endpoints, what requests can be made and what response can be expected, is a must for any RESTful API. For this purpose, we will use RAML to design, document and test the GraphSpace REST APIs.
After we are done documenting the REST APIs in RAML, we will start writing tests for the resources of API using Ra Python library. Ra is a test suite generator and helper library for testing APIs described in RAML. It provides default automatic testing of resources defined in the RAML to validate responses.We will use Ra along with pytest for generating the test suite.
- Work on some issues and submit patches in GraphSpace repository.
- Research more about implementing Python clients for REST APIs, unit testing, documentation using Sphinx and RAML tools for generating docs and test suite.
- Read through the existing documentation of the GraphSpace RESTful APIs.
- Execute all GraphSpace RESTful APIs to understand how they work.
- Discuss the flow of action for the project and finalize a work plan with the mentors and other developers.
- Write up a tutorial on how to use GraphSpace RESTful APIs. [Blog]
- Write code for the core modules of the Python package, i.e., client initialization, making request.
- Implement some basic graph API methods.
- Simultaneously write tests for the written code.
- Write up a tutorial on how to implement a sample Python client for RESTful APIs. [Blog]
- Implement API methods related to groups.
- Simultaneously write tests.
- 26 June - 30 June: (Phase 1 Evaluation)
- Cleaning up the code and removing bugs (if any).
- Preparing and submitting for Phase 1 evaluation.
- Implement the API methods related to layout and tags.
- Simultaneously write tests.
- Write up a blog post about my progress in the project.
- Read through the documentation of Sphinx to familiarize myself with it.
- Start writing documentation for the package.
- Code refactoring and fixing bugs(if required).
- Preparing and submitting for Phase 2 evaluation.
- Complete the usage documentation.
- Configure the package and upload to PyPI.
- Write up a tutorial on how to setup and upload package to PyPI.
- Design GraphSpace API specs using RAML.
- Generate HTML documentation from RAML file.
- Reread the documentation of Ra and generate test suite using it.
- Write up a tutorial on how to design sample API methods using RAML, document and test them.
- Complete any incomplete work.
- Refine the documentation.
- Wrap up the work done throughout summer.
- Make final submission.