Add a new API endpoint in Valence

In this Guide, you will find information on how to add new API in to Valence. This guide assumes that Valence environment is already setup (if not please go through the readme.rst).

Interacting with Valence

Before starting modification/adding a new functionality in Valence, it is suggested to check that the valence has been setup properly. This could be done by making some REST calls to the existing APIs and verifying their response.

Note

curl or some other GUI REST clients(like Postman plugin for Chrome browser) could be used for making the REST calls.

$ curl http://localhost:8181/v1

The above REST API call will return a json with valence version specific details. This ensure that Valence has been setup rightly.

Example ‘Hello World’ API implementation

Consider we want to implement a new API /v1/example that returns “hello world” json.

1. Create a python module inside api/v1 directory that handles the API call

   #valence/api/v1/example.py
   
   from flask import request
   from flask_restful import Resource
   import logging
   
   LOG = logging.getLogger(__name__)
   
   class Example(Resource):
       def get(self):
       LOG.debug("GET /example")
       return {“msg” : “hello world”}
   

   Note

   Check the valence/common/utils.py for commonly used functions and valence/common/exceptions.py for valence structured errors and standard confirmation messages.

2. Add a new route at ‘routes.py’ to receive requests at particular URL extension

   from valence.api.v1.example import Example
   ...
   ...
   api.add_resource(Example, '/v1/example',
                               endpoint='example')
   

3. Start/Restart the valence server

   $ python -m valence.cmd.api
   

   Note

   Ensure config(/etc/valence/valence.conf) and log(/var/log/valence/valence.log) files exists.

4. Test the service manually by issuing a GET request to /v1/example

   $ curl http://localhost:8181/v1/example
   

5. Run tox testing to check pep8 and python2.7 compatibility. This should be ran from the valence root directory(where tox.ini is present)

   $ tox -e pep8,py27
   

6. Update the automated testing scripts to include the new API.

   Getting used to writing testing code and running this code in parallel is considered as a good workflow. Whenever an API for valence is implemented, it is necessary to include the corresponding test case in the testing framework. Currently, valence uses pythons unittest module for running the test cases.

   Tests scripts are located in <valence_root>/valence/tests directory

   Note

   valence/tests/__init__.py contains the base class for FunctionalTest

   Consider implementing an functional testcase for our /example(Add a new API endpoint in Valence) API

   The characteristics of /example(Add a new API endpoint in Valence) API

   • REST Method : GET
   • Parameters : Nil
   • Expected Response Status : 200
   • Expected Response JSON : {“msg” : “hello world”}

   To implement a testcase for the /example api,

   Create a class in valence/tests/functional/test_functional.py which inherits the FunctionalTest class from valence/tests/__init__.py i.e.

   # valence/tests/functional/test_functional.py
   
   class TestExampleController(FunctionalTest):
   
       def test_example_get(self):
           response = self.app.get('/example')
           #Call GET method of /example from Flask APP
           #If REST call went fine, we expect HTTP STATUS 200 along with JSON
           assert response.status_code == 200
           #Test the status
           assert response["msg"] == "hello world"
           #Test the response message
           #likely we could test headers for content-type..etc
   
       def test_example_post(self):
           #suppose consider if POST is implemented & returns STATUS 201
           response = self.app.post('/example')
           assert response.status_code == 201
   

   The above is a very basic example which could be extended to test complex JSONs and response headers.

   Also for every new code added, it is better to do pep8 and other python automated syntax checks. As we have tox integrated in to valence, this could be achieved by, running the below command from the valence root directory(where tox.ini is present)

   $ tox -e pep8,py27