API Guide

About the API

Avni API is available at /api of your Avni server. Avni offers four resources - subject, enrolment, programEncounter and encounter. Currently, Avni supports the only authentication and pulling data. Other APIs will be added over time, but if you need them for your project please contact us.

Please note that there are many rest endpoints in Avni which are used for communication between avni mobile field app and avni web app. These are not meant for integration with third-party applications/services because they have not been designed for that purpose and hence are not documented.

If you are unfamiliar with Avni's domain model then read the following pages first, but in very short - subject is a top-level entity, enrolments and encounters are children of the subject and finally, programEncounters are children of enrolment.

  1. Terminology
  2. Implementer's concept guide - Introduction

Helpful Reference

  1. Swagger documentation is available here:
    https://app.swaggerhub.com/apis-docs/samanvay/avni-external/1.0.0

  2. If you use Postman you can use this public collection:
    https://www.getpostman.com/collections/cd269030533a58e1c072

Pulling data from Avni

If your objective is to pull data from Avni into your own database then you should use /api/subjects, /api/enrolments, and so on. These endpoints provide the response in the form of pages of 100 entries each by default (see the swagger documentation). The entities in these pages are arranged chronologically i.e. it will give the oldest entity first followed by newer and so on. The chronology is followed within the page and in page order.

The lastModifiedDateTime field is the key. If you are reading the entities for the first time it is advisable that you start from something like 1900-01-01T00:00:00.001Z. Once you finish reading all the entities you can store the last entry's date, and next time you can start from the value of the field "Last modified at" (not inclusive) in the audit section of the last entity you have successfully read.

Note that entities can be repeated over time if the same entity has been updated by the user.

Authentication

  1. Using the Avni Admin web app set up a user that you will be using to login via the API. This user should have the role User. Ensure that the user is not challenged with a change in the password on the first login. You can do that by logging in once from the web application.
  2. Avni uses AWS Cognito for authentication, hence the API code has to authenticate itself too. Please use the following references for authenticating with Cognito for various languages.
    - Java (check the signIn( ) method in the example) - Readme
    - JavaScript - Readme
    - Python - Readme
  3. The token provided by Cognito has to be used in the API (as documented in swagger)

Recommendation (not a requirement)

  1. If you are pulling the data in a background process, write your code such that it can handle failure elegantly. The failure can happen with the network or in your code. Most likely you would need to save the lastModfiedDateTime value for each entity in your database. So that when the background processes run subsequent times it can read it from the database. If you save in the memory and your server has restarted you may lose the context of how much you have already read.
  2. For the background process, consider the transaction boundary carefully between saving the lastModifiedDateTime and the actual entity in your system. A transaction boundary where one entity is processed and lastModifiedDateTime is updated is the best. But you may choose some other solution.
  3. This may be obvious but you need to run the background process in a sequence so that you process all the subjects first, followed by their respective programEnrolments and so on.