1.20 Metadata versioning

This section explains the Metadata Versioning APIs available starting 2.24

Query Parameters
Name Required Description
versionName false If this parameter is not specified, it will return the current version of the system or otherwise it will return the details of the versionName passed as parameter. (versionName is of the syntax “Version_<id>”

1.20.1 Get metadata version examples

Example: Get the current metadata version of this system

Sample request:

curl -u admin:district "https://play.dhis2.org/dev/api/metadata/version"

Sample response:

{
    "name": "Version_4",
    "created": "2016-06-30T06:01:28.684+0000",
    "lastUpdated": "2016-06-30T06:01:28.685+0000",
    "externalAccess": false,
    "displayName": "Version_4",
    "type": "BEST_EFFORT",
    "hashCode": "848bf6edbaf4faeb7d1a1169445357b0",
    "id": "Ayz2AEMB6ry"
}

Example: Get the details of version with name “Version_2”

Sample request:

curl -u admin:district "https://play.dhis2.org/dev/api/metadata/version?versionName=Version_2"

Sample response:

{
    "name": "Version_2",
    "created": "2016-06-30T05:59:33.238+0000",
    "lastUpdated": "2016-06-30T05:59:33.239+0000",
    "externalAccess": false,
    "displayName": "Version_2",
    "type": "BEST_EFFORT",
    "hashCode": "8050fb1a604e29d5566675c86d02d10b",
    "id": "SaNyhusVxBG"
}
  • /api/metadata/version/history - This api will return the list of all metadata versions of the system on which it is invoked.
Query Parameters

Name

Required

Description

baseline

false

If this parameter is not specified, it will return list of all metadata versions. Otherwise we need to pass a versionName parameter of the form “Version_<id>”. It will then return the list of versions present in the system which were created after the version name supplied as the query parameter.

1.20.2 Get list of all metadata versions

Example: Get the list of all versions in this system

Sample request:

curl -u admin:district "https://play.dhis2.org/dev/api/metadata/version/history"

Sample response:

{
    "metadataversions": [{
        "name": "Version_1",
        "type": "BEST_EFFORT",
        "created": "2016-06-30T05:54:41.139+0000",
        "id": "SjnhUp6r4hG",
        "hashCode": "fd1398ff7ec9fcfd5b59d523c8680798"
     }, {
         "name": "Version_2",
         "type": "BEST_EFFORT",
         "created": "2016-06-30T05:59:33.238+0000",
         "id": "SaNyhusVxBG",
         "hashCode": "8050fb1a604e29d5566675c86d02d10b"
     }, {
         "name": "Version_3",
         "type": "BEST_EFFORT",
         "created": "2016-06-30T06:01:23.680+0000",
         "id": "FVkGzSjAAYg",
         "hashCode": "70b779ea448b0da23d8ae0bd59af6333"
     }]
}

Example: Get the list of all versions in this system created after “Version_2”

Sample request:

curl -u admin:district "https://play.dhis2.org/dev/api/metadata/version/history?baseline=Version_2"

Sample response:

{
    "metadataversions": [{
        "name": "Version_3",
        "type": "BEST_EFFORT",
        "created": "2016-06-30T06:01:23.680+0000",
        "id": "FVkGzSjAAYg",
        "hashCode": "70b779ea448b0da23d8ae0bd59af6333"
    }, {
        "name": "Version_4",
        "type": "BEST_EFFORT",
        "created": "2016-06-30T06:01:28.684+0000",
        "id": "Ayz2AEMB6ry",
        "hashCode": "848bf6edbaf4faeb7d1a1169445357b0"
    }]
 }
  • /api/metadata/version/create - This api will create the metadata version for the version type as specified in the parameter.
Query Parameters

Name

Required

Description

type

true

The type of metadata version which needs to be created.

  • BEST_EFFORT

  • ATOMIC

Users can select the type of metadata which needs to be created. Metadata Version type governs how the importer should treat the given version. This type will be used while importing the metadata. There are two types of metadata.

  • BEST_EFFORT - This type suggests that missing references can be ignored and the importer can continue importing the metadata (e.g. missing data elements on a data element group import).

  • ATOMIC - ensures a strict type checking of the metadata references and the metadata import will fail if any of the references do not exist.

Note

It’s recommended to have ATOMIC type of versions to ensure that all systems (central and local) have the same metadata. Any missing reference is caught in the validation phase itself. Please see the importer details for better understanding.

1.20.3 Create metadata version

Example: To create metadata version of type BEST_EFFORT

Sample request:

curl -X POST -u admin:district "https://play.dhis2.org/dev/api/metadata/version/create?type=BEST_EFFORT"

Sample response:

{
    "name": "Version_1",
    "created": "2016-06-30T05:54:41.139+0000",
    "lastUpdated": "2016-06-30T05:54:41.333+0000",
    "externalAccess": false,
    "publicAccess": "--------",
    "user": {
        "name": "John Traore",
        "created": "2013-04-18T17:15:08.407+0000",
        "lastUpdated": "2016-04-06T00:06:06.571+0000",
        "externalAccess": false,
        "displayName": "John Traore",
        "id": "xE7jOejl9FI"
    },
    "displayName": "Version_1",
    "type": "BEST_EFFORT",
    "hashCode": "fd1398ff7ec9fcfd5b59d523c8680798",
    "id": "SjnhUp6r4hG"
}
  • /api/metadata/version/{versionName}/data - This api will download the actual metadata specific to the version name passed as path parameter.

  • /api/metadata/version/{versionName}/data.gz - This api will download the actual metadata specific to the version name passed as path parameter in a compressed format (gzipped).

Path parameters

Name

Required

Description

versionName

true

Path parameter of the form “Version_<id>” so that the api downloads the specific version

1.20.4 Download version metadata

Example: Get the actual metadata for “Version_5”

Sample request:

curl -u admin:district "https://play.dhis2.org/dev/api/metadata/version/Version_5/data"

Sample response:

{
    "date": "2016-06-30T06:10:23.120+0000",
    "dataElements": [{
        "code": "ANC 5th Visit",
        "created": "2016-06-30T06:10:09.870+0000",
        "lastUpdated": "2016-06-30T06:10:09.870+0000",
        "name": "ANC 5th Visit",
        "id": "sCuZKDsix7Y",
        "shortName": "ANC 5th Visit ",
        "aggregationType": "SUM",
        "domainType": "AGGREGATE",
        "zeroIsSignificant": false,
        "valueType": "NUMBER",
        "categoryCombo": {
            "id": "p0KPaWEg3cf"
        },
        "user": {
            "id": "xE7jOejl9FI"
        }
    }]
}