Codeset

In its simplest form, a Code Set can be represented as follows:

Response body (JSON)

{
    "id": "81d00110-40e3-4ec0-b279-6004fa1b9b52",
    "domainType": "CodeSet",
    "label": "Sample Codeset",
    "aliases": [
        "sample"
    ],
    "description": "Example of a Codeset",
    "author": "NHS Digital",
    "organisation": "NHS Digital",
    "documentationVersion": "2.0.0",
    "lastUpdated": "2019-10-03T12:00:05.95Z",
    "classifiers": [
        {
            "id": "2fd9e8c7-4545-42f4-99a3-f93f14d35786",
            "label": "NIHR Health Data Finder",
            "lastUpdated": "2019-10-03T09:15:37.323Z"
        }
    ],
    "type": "CodeSet",
    "finalised": false,
}

The fields are as follows:

• id (UUID): The unique identifier of this code set
• domainType (Type): The domain type of this catalogue object - always CodeSet in this case
• label (String): The human-readable identifier of this code set. The combination of label and documentationVersion are unique across the catalogue
• aliases (Set(String)): Any other names by which this code set is known
• description (String): A long description of the code set, and any important characteristics of the data. This field may include HTML, or MarkDown.
• author (String): The names of those creating and maintaining this code set (not any underlying dataset itself)
• organisation (String): The name of the organisation holding the dataset
• documentationVersion (Version): The version of the description of an underlying dataset
• lastUpdated (DateTime): The date/time when this code set was last modified
• classifiers (Set(Classifier)): The id, label and lastUpdated date of any classifiers used to tag or categorise this code set (see classifiers)
• type (CodeSet Type): Will always be defined as CodeSet.
• finalised (Boolean): Whether this code set has been 'finalised', or is in draft mode

Endpoints which return multiple code sets typically include sufficient fields for generating links on the interface - a separate call to return the details of the Code Set is usually required.

As well as the endpoints listed below, a Code Set is also a CatalogueItem, and so a Code Set identifier can also be used as the parameter to any of those endpoints

List all code sets

The following endpoint returns a paginated list of all code set objects readable by the current user:

/api/codeSets

This endpoint returns all the code sets within a particular folder; again, this result is paginated.

/api/folders/{folderId}/codeSets

Get information about a particular code set

This endpoint provides the default information about a code set, as per the JSON at the top of the page.

/api/codeSets/{id}

Create code set

To create a new code set from scratch, use the following post endpoint. Within the body of this call, you should include a folder identifier.

/api/codeSets

There are two ways of versioning code set in the catalogue. To create an entirely new version of a model, please use the following endpoint:

/api/codeSets/{codeSetId}/newBranchModelVersion

The name must be different to the original model.

To create a new 'documentation version', use the following endpoint:

/api/codeSets/{codeSetId}/newDocumentationVersion

By default, this will supersede the original data model.

It is also possible to branch and fork code sets to create drafts before finalising them. To create a new branch from an existing code set:

/api/codeSets/{codeSetId}/newBranchModelVersion

Request body (JSON)

{
    "branchName": "newBranch"
}

To create a fork of the original data model:

/api/codeSets/{codeSetId}/newForkModel

Request body (JSON)

{
    "label": "newForkLabel"        
}

Update code set

To edit the primitive properties of a code set, use the following endpoint, with a body similar to the JSON described at the top of this page:

/api/codeSets/{id}

To move a code set from one folder to another, call the following, using the id fields for the code set, and the new folder:

/api/folders/{folderId}/codeSets/{codeSetId}

Alternatively, you can call this equivalent endpoint:

/api/codeSets/{codeSetId}/folder/{folderId}

To move a code set from a draft state to 'finalised', use the following endpoint:

/api/codeSets/{codeSetId}/finalise

Sharing

To allow a code set to be read by any authenticated user of the system, use the following endpoint:

/api/codeSets/{codeSetId}/readByAuthenticated

... and to remove this flag, use the following:

/api/codeSets/{codeSetId}/readByAuthenticated

Similarly, to allow the code set to be publicly readable - ie. readable by any unauthenticated user of the system, use the following endpoint:

/api/codeSets/{codeSetId}/readByEveryone

... and the following to remove this flag:

/api/codeSets/{codeSetId}/readByEveryone

Delete code set

To delete a code set, use the following endpoint. The permanent parameter is a boolean value that controls whether a 'hard' or 'soft' delete is used if the user is an administrator.

/api/codeSets/{id}?permanent={true/false}

An administrator is able to restore a 'soft' deleted code set using the following endpoint:

/api/admin/codeSets/{id}/undoSoftDelete

Import / export a code set

To export a code set using a particular export plugin, you will need to know the namespace, the name, and the version of the plugin. The following endpoint can be used to export multiple code sets:

/api/codeSets/export/{exporterNamespace}/{exporterName}/{exporterVersion}

To export a single code set, you can use the following endpoint with the id of the code sets specified:

/api/codeSets/{codeSetId}/export/{exporterNamespace}/{exporterName}/{exporterVersion}

Similarly, to import one or more code sets, the namespace, name and version of the import plugin must be known. The body of this method should be the parameters for the import, including any files that are required.

/api/codeSets/import/{importerNamespace}/{importerName}/{importerVersion}