## Introduction APMIS (Afghanistan Polio Management Information System) is a supplemental immunization activities management system to manage the vaccination activities in the country. APMIS API v1 is built from the ground up with a REST API that makes it easy for developers and sysadmins to automate access to campaign data through REST endpoints. These docs describe how to use the [APMIS](https://afghanistan-apmis.com/) API. We hope you enjoy these docs, and please don't hesitate to [file an issue](https://github.com/xlg8/APMIS-Project/issues/new) if you see anything missing. ## Use Cases There are many reasons to use the APMIS API. The most common use case is to gather report information for a given campaign, so that you can build custom reports in software you're most familiar with, such as Excel or Power Bi. ## Authorization To authenticate an API request, you should provide your APMIS **REST USER** username and password in the `Authorization` header. This can also be passed through a browser provided prompt at your first request call. Please note that this is likely to leave traces in things like your history if accessing the API through a browser. ```https GET /sormas-rest/v1/campaigns ``` | Parameter | Type | Description | | :--- | :--- | :--- | | `username` | `string` | **Required**. Your REST USER USERNAME | | `password` | `string` | **Required**. Your REST USER PASSWORD| ## Responses All API endpoints return the JSON representation of the resources requested. However, if an invalid request is submitted, or some other error occurs, APMIS returns a JSON response in the following format: ```javascript { "message" : string, "success" : bool, "data" : string } ``` The `message` attribute contains a message commonly used to indicate errors. The `success` attribute describes if the transaction was successful or not. The `data` attribute contains any other metadata associated with the response. This will be an escaped string containing JSON data. ## Status Codes APMIS returns the following status codes in its API: | Status Code | Description | | :--- | :--- | | 200 | `OK` | | 400 | `BAD REQUEST` | | 404 | `NOT FOUND` | | 500 | `INTERNAL SERVER ERROR` | ## Endpoints The following endpoints are available in this version | Endpoint | Parameter| Description | | :--- | :--- |:--- | | /campaigns| |return a list of all active campaigns | | /campaigns/{uuid}| Campaign uuid `Long` | return the campaign information a campaign| | /campaigns/{uuid}/forms| Campaign uuid `Long` | return the campaign form metas of the campaign | | /campaigns/{campaign_uuid}/forms/{form_uuid} | Campaign uuid `Long`, Form uuid `Long` | return all campaign form data of a form associated with the campaign| The `/v1/campaigns` is the starting point for all requests. ## Fetching Geographical Units History ## Overview The Administrative Divisions History API provides access to the historical records of changes made to various geographical administrative units (provinces and districts). These endpoints track the chronological evolution of administrative divisions, capturing modifications such as name changes, status updates, and other administrative edits. | Endpoint | Parameter| Description | | :--- | :--- |:--- | |/areas/areaHistory| | This endpoint retrieves the complete modification history for all regions identified| |/areas/areaHistory?getAreaHistory={uuid} | Region UUID | This endpoint retrieves the complete modification history for a specific regions identified| |/regions/provincesHistory| | This endpoint retrieves the complete modification history for all provinces identified| |/regions/provincesHistory?getProvinceHistory={uuid} | Province UUID | This endpoint retrieves the complete modification history for a specific province identified| |/districts/districtsHistory| | This endpoint retrieves the complete modification history for all districts identified| |/districts/districtsHistory?getDistrictHistory={uuid} | District UUID | This endpoint retrieves the complete modification history for a specific district identified| |/communities/clustersHistory| | This endpoint retrieves the complete modification history for all clusters identified| |/communities/clustersHistory?getClusterHistory={uuid} | Cluster UUID | This endpoint retrieves the complete modification history for a specific cluster identified| ## Form Versioning ## Overview The Campaign Forms Versions API provides access to the historical records of changes made to various campaign forms. These endpoints track the chronological evolution of campaign forms per edit/update, capturing modifications such as duplication and update. | Endpoint | Parameter| Description | | :--- | :--- |:--- | |/campaignFormMeta/getFormMetaHistory| | This endpoint retrieves the complete modification history for all campaign forms identified| |/campaignFormMeta/getFormMetaHistory?getFormMetaHistoryByUuid={uuid} | Campaign Form Meta UUID | This endpoint retrieves the complete modification history for a specific campaign formm identified| ## Record Versioning ## Overview The Campaign Forms Data Record Versions API provides access to the historical records of changes made to various campaign data forms. These endpoints track the changes made to a campaign forms per edit/update, capturing modifications such as formvalues, and geographical unit changes, published and verified statuses e.t.c. | Endpoint | Parameter| Description | | :--- | :--- |:--- | |/apmisrestserver/formdatahistory?fetchFromIndex={index}&fetchSize={size}| Index (Offset), Size(Maximum Result Size) | This endpoint retrieves the complete modification history for all campaign forms identified within the maximum fetch size| |/apmisrestserver/formdatahistory?fetchFromIndex={index}&fetchSize={size}&getRecordHistory={uuids} | Index (Offset), Size(Maximum Result Size) , Uuids(Single record or Multiple record uuids(s) | This endpoint retrieves the complete modification history for campaign form records as well as one or more identified records using their uuids| |/apmisrestserver/formdatahistorycount?getRecordHistoryCount={uuid(s)}|Uuids (uuid) | Returns records counts for all records and returns the count of record when provided with the uuid query parameter. uuid are to be seperated by comma ","| # Campaign Form Data API The **Campaign Form Data API** provides access to campaign form data records. It supports paginated retrieval of records and optional filtering by **Campaign UUID** and **Campaign Form UUID**, allowing clients to retrieve data for a specific campaign, a specific form, or both. | **Endpoint** | **Parameters** | **Description** | |---|---|---| | `/apmisrestserver/campaignformdata?fetchDataFromIndex={index}&dataFetchSize={size}&includeArchived={true/false}` | Index (Offset), Size (Maximum Result Size), Include Archived | Retrieves campaign form data records based on the specified pagination and archive settings. | | `/apmisrestserver/campaignformdata?fetchDataFromIndex={index}&dataFetchSize={size}&includeArchived={true/false}&campaign_uuid={uuid}` | Index (Offset), Size (Maximum Result Size), Include Archived, Campaign UUID | Retrieves campaign form data records associated with the specified campaign UUID. | | `/apmisrestserver/campaignformdata?fetchDataFromIndex={index}&dataFetchSize={size}&includeArchived={true/false}&campaignForm_uuid={uuid}` | Index (Offset), Size (Maximum Result Size), Include Archived, Campaign Form UUID | Retrieves campaign form data records associated with the specified campaign form UUID. | | `/apmisrestserver/campaignformdata?fetchDataFromIndex={index}&dataFetchSize={size}&includeArchived={true/false}&campaign_uuid={uuid}&campaignForm_uuid={uuid}` | Index (Offset), Size (Maximum Result Size), Include Archived, Campaign UUID, Campaign Form UUID | Retrieves campaign form data records matching both the specified campaign UUID and campaign form UUID. | ## Query Parameters | **Parameter** | **Description** | |---|---| | `fetchDataFromIndex` | Specifies the starting index (offset) from which records should be retrieved. | | `dataFetchSize` | Specifies the maximum number of records to return. | | `includeArchived` | Determines whether archived campaign form data records should be included in the result. | | `campaign_uuid` | Optional campaign UUID used to filter records belonging to a specific campaign. | | `campaignForm_uuid` | Optional Campaign Form UUID used to filter records belonging to a specific campaign form. | ## Example ### Retrieve campaign form data for a specific campaign /apmisrestserver/campaignformdata?fetchDataFromIndex=0&dataFetchSize=100&includeArchived=false&campaign_uuid={campaignUuid}&campaignForm_uuid={campaignFormUuid} The campaign_uuid and campaignForm_uuid parameters are optional and can be used independently or together to narrow the returned campaign form data records. # Population Data Endpoint The **Population Data Endpoint** provides a paginated interface for retrieving population records stored in APMIS. It is intended to fetch population data in manageable batches rather than retrieve the entire dataset in a single request. It supports paginated retrieval of records and optional filtering . Primary capabilities: - Retrieve population data in batches using pagination. - Return records in a deterministic sort order based on campaign, region, district, and creation date. - Limit the number of records returned per request to help manage server load and response sizes. | **Endpoint** | **Parameters** | **Description** | |---|---|---| | `/apmisrestserver/populationdata?fetchFromIndex={index}&fetchSize={size}` | Index (Offset), Size (Maximum Result Size) | Retrieves population data records based on the specified pagination settings. | ## Query Parameters | **Parameter** | **Description** | |---|---| | `fetchDataFromIndex` | Zero-based index of the first record to retrieve. | | `dataFetchSize` | Maximum number of records to retrieve in the request. | ## Example GET /apmisrestserver/populationdata?fetchFromIndex=0&fetchSize=100 GET https://your-apmis-server/sormas-rest/apmisrestserver/populationdata?fetchFromIndex=0&fetchSize=1000 This request should return the first 100 records from the population data records. Validation and edge cases The implementation contains the following validation condition: Input condition | Expected behaviour -- | -- fetchSize > 5000 | Returns an empty list. fetchSize < 0 | Returns an empty list. fetchFromIndex < 0 | Returns an empty list. fetchSize = 0 | No maximum result count is applied by the shown pagination logic. fetchFromIndex = 0 | Starts at the first record. fetchFromIndex = null | No starting offset is applied by the shown pagination logic. fetchSize = null | No maximum result count is applied by the shown pagination logic. Offset beyond the available records | Returns an empty list.