Chapter 1. Web API

Table of Contents

1.1. Introduction
1.2. Authentication
1.2.1. Basic Authentication
1.2.2. OAuth2
1.3. Error and info messages
1.4. Date and period format
1.5. Identifier schemes
1.6. Browsing the Web API
1.6.1. Translation
1.6.2. Translation API
1.6.3. Web API versions
1.7. Metadata object filter
1.7.1. Logical operators
1.8. Metadata field filter
1.8.1. Field transformers
1.9. Metadata create, read, update, delete, validate
1.9.1. Create / update parameters
1.9.2. Creating and updating objects
1.9.3. Deleting objects
1.9.4. Adding and removing objects in collections
1.9.5. Validating payloads
1.9.6. Partial updates
1.10. Metadata export
1.10.1. Metadata export examples
1.10.2. Metadata export with dependencies
1.11. Metadata import
1.12. Metadata audit
1.13. AMQP/RabbitMQ integration
1.14. CSV metadata import
1.14.1. Data elements
1.14.2. Organisation units
1.14.3. Validation rules
1.14.4. Option sets
1.14.5. Collection membership
1.14.6. Other objects
1.15. Deleted objects
1.16. Favorites
1.17. File resources
1.17.1. File resource constraints
1.18. Metadata versioning
1.18.1. Get metadata version examples
1.18.2. Get list of all metadata versions
1.18.3. Create metadata version
1.18.4. Download version metadata
1.19. Metadata Synchronization
1.19.1. Sync metadata version
1.20. Data values
1.20.1. Sending data values
1.20.2. Sending bulks of data values
1.20.3. Import parameters
1.20.4. CSV data value format
1.20.5. Generating data value set template
1.20.6. Reading data values
1.20.7. Sending, reading and deleting individual data values
1.21. ADX data format
1.21.1. The adx root element
1.21.2. The group element
1.21.3. ADX period definitions
1.21.4. Data values
1.21.5. Importing data - HTTP POST
1.21.6. Exporting data - HTTP GET
1.22. Events
1.22.1. Sending events
1.22.2. CSV Import / Export
1.22.3. Querying and reading events
1.23. Program rules
1.23.1. Program rule model
1.23.2. Creating program rules
1.24. Forms
1.25. Validation
1.26. Validation Results
1.27. Data integrity
1.27.1. Running data integrity
1.27.2. Fetching the result
1.28. Indicators
1.28.1. Aggregate indicators
1.28.2. Program indicators
1.28.3. Expressions
1.29. Complete data set registrations
1.29.1. Completing data sets
1.29.2. Reading complete data set registrations
1.29.3. Un-completing data sets
1.30. Data approval
1.30.1. Get approval status
1.30.2. Approve data
1.30.3. Bulk approve data
1.31. Auditing
1.31.1. Aggregate data value audits
1.31.2. Tracked entity data value audits
1.31.3. Tracked entity attribute value audits
1.31.4. Data approval audits
1.32. Message conversations
1.32.1. Writing and reading messages
1.32.2. Managing messages
1.32.3. Tickets
1.33. Interpretations
1.33.1. Reading interpretations
1.33.2. Writing interpretations
1.33.3. Updating and removing interpretations
1.33.4. Creating interpretation comments
1.33.5. Updating and removing interpretation comments
1.33.6. Liking interpretations
1.34. Viewing analytical resource representations
1.35. Plugins
1.35.1. Embedding pivot tables with the Pivot Table plug-in
1.35.2. Embedding charts with the Visualizer chart plug-in
1.35.3. Embedding maps with the GIS map plug-in
1.35.4. Creating a chart carousel with the carousel plug-in
1.36. SQL views
1.36.1. Criteria
1.36.2. Variables
1.36.3. Filtering
1.37. Dashboard
1.37.1. Browsing dashboards
1.37.2. Searching dashboards
1.37.3. Creating, updating and removing dashboards
1.37.4. Adding, moving and removing dashboard items and content
1.38. Analytics
1.38.1. Request query parameters
1.38.2. Dimensions and items
1.38.3. The dx dimension
1.38.4. Response formats
1.38.5. Constraints
1.38.6. Data value set format
1.38.7. Raw data format
1.38.8. Debugging
1.39. Event analytics
1.39.1. Dimensions and items
1.39.2. Request query parameters
1.39.3. Event query analytics
1.39.4. Event aggregate analytics
1.39.5. Event clustering analytics
1.39.6. Event count and extent analytics
1.40. Data set report
1.41. Push Analysis
1.42. Data usage analytics
1.42.1. Request query parameters
1.42.2. Create view events (POST)
1.42.3. Retrieve aggregated usage analytics report (GET)
1.42.4. Retrieve top favorites
1.42.5. Response format
1.42.6. Retrieve statistics for a favorite
1.43. Geospatial features
1.43.1. GeoJSON
1.44. Generating resource and analytics tables
1.45. Maintenance
1.46. System resource
1.46.1. Generate identifiers
1.46.2. View system information
1.46.3. Check if username and password combination is correct
1.46.4. View asynchronous task status
1.46.5. Get appearance information
1.47. Locales
1.47.1. UI locales
1.47.2. Database content locales
1.48. Translations
1.48.1. Create translation
1.48.2. Get translations
1.49. Short Message Service (SMS)
1.49.1. Outbound SMS service
1.49.2. Inbound SMS service
1.49.3. Gateway service administration
1.49.4. Gateway configuration
1.50. SMS Commands
1.50.1. API End Points
1.51. Program Messages
1.51.1. Sending program messages
1.51.2. Retrieving and deleting program messages
1.51.3. Querying program messages
1.52. Users
1.52.1. User query
1.52.2. User credentials query
1.52.3. User account create and update
1.52.4. User account invitations
1.52.5. User replication
1.53. Current user information and associations
1.54. System settings
1.55. User settings
1.56. Organisation units
1.56.1. Get list of organisation units
1.56.2. Get organisation unit with relations
1.57. Data sets
1.57.1. DataSet Notification Template
1.58. Filled organisation unit levels
1.59. Static content
1.60. Configuration
1.61. Read-Only configuration service
1.62. Internationalization
1.63. SVG conversion
1.64. Tracked entity instance management
1.64.1. Creating a new tracked entity instance
1.64.2. Updating a tracked entity instance
1.64.3. Deleting a tracked entity instance
1.64.4. Enrolling a tracked entity instance into a program
1.64.5. Update strategies
1.64.6. Create and enroll tracked entity instances
1.64.7. Generated tracked entity instance attributes
1.65. Tracked entity instance query
1.65.1. Request syntax
1.65.2. Response format
1.66. Tracked entity instance grid query
1.66.1. Request syntax
1.66.2. Response format
1.67. Enrollment instance query
1.67.1. Request syntax
1.67.2. Response format
1.68. Tracker bulk deletion
1.69. Email
1.69.1. System notification
1.69.2. Outbound emails
1.69.3. Test message
1.70. Sharing
1.70.1. Get sharing status
1.70.2. Set sharing status
1.71. Scheduling
1.72. Schema
1.73. UI customization
1.73.1. Javascript
1.73.2. CSS
1.74. Synchronization
1.74.1. Data push
1.74.2. Metadata pull
1.74.3. Availability check
1.75. Apps
1.75.1. Get apps
1.75.2. Install an app
1.75.3. Delete an app
1.75.4. Reload apps
1.75.5. Apps shared between instances
1.76. App store
1.76.1. Get apps
1.76.2. Install apps
1.77. Data store
1.77.1. Data store structure
1.77.2. Get keys and namespaces
1.77.3. Create values
1.77.4. Update values
1.77.5. Delete keys
1.78. User data store
1.78.1. User data store structure
1.78.2. Get namespaces
1.78.3. Get keys
1.78.4. Get value
1.78.5. Create value
1.78.6. Update existing value
1.78.7. Delete key
1.78.8. Delete namespace
1.79. Predictors
1.79.1. Creating a predictor
1.79.2. Generating predicted values
1.80. Min-max data elements
1.80.1. Add/Update min-max data element
1.80.2. Delete min-max data element
1.81. Lock exceptions
1.82. Tokens
1.82.1. Google Service Account
1.83. Analytics table hooks
1.83.1. Hook fields
1.83.2. Creating hooks
1.84. Metadata repository

The Web API is a component which makes it possible for external systems to access and manipulate data stored in an instance of DHIS2. More precisely, it provides a programmatic interface to a wide range of exposed data and service methods for applications such as third-party software clients, web portals and internal DHIS2 modules.

1.1. Introduction

The Web API adheres to many of the principles behind the REST architectural style. To mention some few and important ones:

  1. The fundamental building blocks are referred to as resources. A resource can be anything exposed to the Web, from a document to a business process - anything a client might want to interact with. The information aspects of a resource can be retrieved or exchanged through resource representations. A representation is a view of a resource's state at any given time. For instance, the reportTable resource in DHIS2 represents a tabular report of aggregated data for a certain set of parameters. This resource can be retrieved in a variety of representation formats including HTML, PDF, and MS Excel.

  2. All resources can be uniquely identified by a URI (also referred to a/s URL). All resources have a default representation. You can indicate that you are interested in a specific representation by supplying an Accept HTTP header, a file extension or a format query parameter. So in order to retrieve the PDF representation of a report table you can supply a Accept: application/pdf header or append .pdf or ?format=pdf to your request URL.

  3. Interactions with the API requires correct use of HTTP methods or verbs. This implies that for a resource you must issue a GET request when you want to retrieve it, POST request when you want to create one, PUT when you want to update it and DELETE when you want to remove it. So if you want to retrieve the default representation of a report table you can send a GET request to e.g. /reportTable/iu8j/hYgF6t, where the last part is the report table identifier.

  4. Resource representations are linkable, meaning that representations advertise other resources which are relevant to the current one by embedding links into itself (please be aware that you need to request href in your field filter to have this working. This feature greatly improves the usability and robustness of the API as we will see later. For instance, you can easily navigate to the indicators which are associated with a report table from the reportTable resource through the embedded links using your preferred representation format.

While all of this might sound complicated, the Web API is actually very simple to use. We will proceed with a few practical examples in a minute.