valence/doc/source/developer-guide/add_new_api.rst

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

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.