Custom Field, Custom Value and List API Changes

We are planning on introducing some new changes to the API related to the organisation of custom fields and the list endpoint in the future. This metadata list endpoint is the endpoint which displays all data for metadata concepts (e.g. the dataset list endpoint is: api/v4/metadata/dataset). This post is a first proposal and a chance to get feedback from users about the changes. The changes described below are not final and may change.

These updates will decrease load times for the list API endpoint. These changes will also improve the use of and presentation of Custom Values. We are making these changes to further facilitate the delivery of the Aristotle App Store and improve the connectivity of developed apps.

We will provide a clear date and direct notice regarding when the changes will be made in the near future. When we provide that notice, we will provide exact specifications for what the changes will look like. Please note that we will not make any of these changes without providing explicit notice. If you have any feedback on these proposed changes please let us know in the comments below.

Custom Value Set Field: customvalue_set

We are planning to change the customvalue_set API contained on metadata concepts. The namespace for the system name will also be displayed. Currently, the custom value set appears as follows:

[
  {
    'name': "Example dataset",
    'id': 1,
    "customvalue_set": [
        {
            "id": 256,
            "name": "Contract Code",
            "field": 6,
            "content": "AA1023"
        },
        ...
    ],
    ...
  },
  ...
]

We will be altering this field so that it appears in a map, or object format. Keys will be the system names for the custom fields, and the value will be the custom value associated.

New proposed specification for the API:

[
  {
    'name': "Example dataset",
    'id': 1,
    "customvalue_set": {
      "dataset:contract_code": "AA1023"
      system_name: value,
    },
    ...
  },
  ...
]

For an interim period - we will allow posting data in the old format to the create endpoint as users get accustomed to the changes. We will notify users when this interim period is over.

Custom Field API:

We are updating the custom field list API to include the namespaced system name. This is a minor change but this will appear as follows:

    {
        "id": 32,
        "order": 1,
        "name": "CustomFieldName",
        "type": "int",
        "system_name": "all:custom_field_system_name",
        "help_text": "",
        "help_text_long": "",
        "hr_type": "Integer",
        "allowed_model": null,
        "visibility": 0,
        "hr_visibility": "Public",
        "state": 0,
        "choices": ""
    },

Metadata List API

Additionally, we will be changing the default metadata concept list API to remove component fields and custom fields. We are making this change to decrease load times experienced with this endpoint. We will introduce the option to include component fields and custom fields specifically or to include all of them. We will clarify exactly how to specify the additional fields which you would like included for the list endpoint. You will still be able to fetch all the components and custom fields at the specific item endpoint using the items id or uuid (e.g. api/v4/metadata/dataset/12).

   
     results": [
   {
            "id": 11152,
            "created": "2023-02-14T13:43:46.139932+11:00",
            "modified": "2023-02-14T13:43:47.125657+11:00",
            "uuid": "1d11fca6-379a-11ec-9226-0a58a9feac02",
            "name": "2020 Patient experience database",
            "definition": "
A database of self-report survey data that describes how users felt about a recent stay in a hospital.",
            "stewardship_organisation": "e91b5f2cdb6611eab8a102395d8b3e72",
            "workgroup": null,
            "version": "",
        },
…
]

Additional fields can be included by using arguments in the url such as the following:

api/v4/metadata/dataset?field=customvalue_set

This will fetch the dataset core data and include the customvalue_set field.

api/v4/metadata/dataset?field=all

This will fetch all the fields on the dataset. This is what the default is currently.

Thank you very much for reading. Please let us know if you have any feedback.
Thanks,

Ben