sdk

dp-dataset-api SDK

Overview

This SDK provides a client for interacting with the dp-dataset-api. It is intended to be consumed by services that require endpoints from the dp-dataset-api. It also provides healthcheck functionality, mocks and structs for easy integration and testing.

Available client methods

Instantiation

Example using New:

package main

import "github.com/ONSdigital/dp-dataset-api/sdk"

func main() {
    client := sdk.New("http://localhost:22000")
}

Example using NewWithHealthClient:

package main

import (
    "github.com/ONSdigital/dp-api-clients-go/v2/health"
    "github.com/ONSdigital/dp-dataset-api/sdk"
)

func main() {
    existingHealthClient := health.NewClient("existing-service-name", "http://localhost:8080")

    client := sdk.NewWithHealthClient(existingHealthClient)
}

Example usage of client

This example demonstrates how the GetDataset() function could be used:

package main

import (
    "context"

    "github.com/ONSdigital/dp-dataset-api/sdk"
)

func main() {
    client := sdk.New("http://localhost:22000")

    // Set headers if you want the request to be authenticated
    headers := sdk.Headers{
        AccessToken: "example-service-token",
    }

    dataset, err := client.GetDataset(context.Background(), headers, "dataset-id")
    if err != nil {
        // Log the error and handle based on error message
    }

    // dataset object can be used as needed...
}

Available functionality

Checker

import "github.com/ONSdigital/dp-healthcheck/healthcheck"

check := &healthcheck.CheckState{}
err := client.Checker(ctx, check)

Health

healthClient := client.Health()

URL

url := client.URL()

GetDataset

import "github.com/ONSdigital/dp-dataset-api/sdk"

// Optional to get unpublished data
headers := sdk.Headers{
    AccessToken: "example-auth-token",
}

dataset, err := client.GetDataset(ctx, headers, "dataset-id")

GetDatasetByPath

import "github.com/ONSdigital/dp-dataset-api/sdk"

// Optional to get unpublished data
headers := sdk.Headers{
    AccessToken: "example-auth-token",
}

dataset, err := client.GetDatasetByPath(ctx, headers, "/path/to/dataset")

GetDatasetCurrentAndNext

import "github.com/ONSdigital/dp-dataset-api/sdk"

// Required as this function returns the DatasetUpdate model which is specific to authorised users
headers := sdk.Headers{
    AccessToken: "example-auth-token",
}

dataset, err := client.GetDatasetCurrentAndNext(ctx, headers, "dataset-id")

GetDatasetEditions

import "github.com/ONSdigital/dp-dataset-api/sdk"

headers := sdk.Headers{
    AccessToken: "example-auth-token",
}

queryParams := &sdk.QueryParams{
    Limit:  10,
    Offset: 5,
}

datasetEditions, err := client.GetDatasetEditions(ctx, headers, queryParams)

GetDatasets

import "github.com/ONSdigital/dp-dataset-api/sdk"

// Required as this function returns thea list with items containing the DatasetUpdate model which is specific to authorised users
headers := sdk.Headers{
    AccessToken: "example-auth-token",
}

queryParams := &sdk.QueryParams{
    Limit:  10,
    Offset: 5,
}

datasets, err := client.GetDatasets(ctx, headers, queryParams)

GetDatasetsInBatches

import "github.com/ONSdigital/dp-dataset-api/sdk"

// Required as this function returns thea list with items containing the DatasetUpdate model which is specific to authorised users
headers := sdk.Headers{
    AccessToken: "example-auth-token",
}

datasets, err := client.GetDatasetsInBatches(ctx, headers, 10, 2)

CreateDataset

import (
    "github.com/ONSdigital/dp-dataset-api/models"
    "github.com/ONSdigital/dp-dataset-api/sdk"
)

headers := sdk.Headers{
    AccessToken: "example-auth-token",
}

datasetToCreate := models.Dataset{
    ID:    "my-dataset-id",
    Title: "Title of this Dataset",
    // populate other required fields as required
}

createdDataset, err := client.CreateDataset(ctx, headers, datasetToCreate)

DeleteDataset

import "github.com/ONSdigital/dp-dataset-api/sdk"

headers := sdk.Headers{
    AccessToken: "example-auth-token",
}

err := client.DeleteDataset(ctx, headers, "dataset-id")

GetEdition

import "github.com/ONSdigital/dp-dataset-api/sdk"

// Optional to get unpublished data
headers := sdk.Headers{
    AccessToken: "example-auth-token",
}

edition, err := client.GetEdition(ctx, headers, "dataset-id", "edition-id")

GetEditions

import "github.com/ONSdigital/dp-dataset-api/sdk"

// Optional to get unpublished data
headers := sdk.Headers{
    ServiceToken: "example-auth-token",
}

queryParams := &sdk.QueryParams{
    Limit:  10,
    Offset: 5,
}

editions, err := client.GetEditions(ctx, headers, "dataset-id", queryParams)

GetVersion

import "github.com/ONSdigital/dp-dataset-api/sdk"

// Optional to get unpublished data
headers := sdk.Headers{
    AccessToken: "example-auth-token",
}

version, err := client.GetVersion(ctx, headers, "dataset-id", "edition-id", "1")

GetVersionWithHeaders

import "github.com/ONSdigital/dp-dataset-api/sdk"

// Optional to get unpublished data
headers := sdk.Headers{
    AccessToken: "example-auth-token",
}

version, err := client.GetVersionWithHeaders(ctx, headers, "dataset-id", "edition-id", "1")

GetVersionV2

import "github.com/ONSdigital/dp-dataset-api/sdk"

// Optional to get unpublished data
headers := sdk.Headers{
    AccessToken: "example-auth-token",
}

version, err := client.GetVersionV2(ctx, headers, "dataset-id", "edition-id", "1")

GetVersionDimensions

import "github.com/ONSdigital/dp-dataset-api/sdk"

// Optional to get unpublished data
headers := sdk.Headers{
    AccessToken: "example-auth-token",
}

versionDimensions, err := client.GetVersionDimensions(ctx, headers, "dataset-id", "edition-id", "1")

GetVersionDimensionOptions

import "github.com/ONSdigital/dp-dataset-api/sdk"

// Optional to get unpublished data
headers := sdk.Headers{
    AccessToken: "example-auth-token",
}

queryParams := &sdk.QueryParams{
    Limit:  10,
    Offset: 5,
}

versionDimensionOptionsList, err := client.GetVersionDimensionOptions(ctx, headers, "dataset-id", "edition-id", "1", "dimension-id", queryParams)

GetVersionMetadata

import "github.com/ONSdigital/dp-dataset-api/sdk"

// Optional to get unpublished data
headers := sdk.Headers{
    AccessToken: "example-auth-token",
}

versionMetadata, err := client.GetVersionMetadata(ctx, headers, "dataset-id", "edition-id", "1")

GetVersions

import "github.com/ONSdigital/dp-dataset-api/sdk"

// Optional to get unpublished data
headers := sdk.Headers{
    ServiceToken: "example-auth-token",
}

queryParams := &sdk.QueryParams{
    Limit:  10,
    Offset: 5,
}

versions, err := client.GetVersions(ctx, headers, "dataset-id", "edition-id", queryParams)

GetVersionsInBatches

import "github.com/ONSdigital/dp-dataset-api/sdk"

// Optional to get unpublished data
headers := sdk.Headers{
    ServiceToken: "example-auth-token",
}

versions, err := client.GetVersionsInBatches(ctx, headers, "dataset-id", "edition-id", 10, 2)

PutDataset

import (
    "github.com/ONSdigital/dp-dataset-api/models"
    "github.com/ONSdigital/dp-dataset-api/sdk"
)

headers := sdk.Headers{
    AccessToken: "example-auth-token",
}

datasetToUpdate := models.Dataset{
    Type: models.Static.String(),
    Description: "this is a dataset",
    // populate other required fields as required
}

err := client.PutDataset(ctx, headers, "dataset-id", datasetToupdate)

PutInstance

import (
    "github.com/ONSdigital/dp-dataset-api/models"
    "github.com/ONSdigital/dp-dataset-api/sdk"
)

headers := sdk.Headers{
    AccessToken: "example-auth-token",
    IfMatch: "ETag"
}

instanceToUpdate := models.UpdateInstance{
    Type: models.CantabularFlexibleTable.String(),
    Edition: "time-series",
    // populate other required fields as required
}

returnedETag, err := client.PutInstance(ctx, headers, "instance-id", instanceToUpdate)

PutMetadata

import (
    "github.com/ONSdigital/dp-dataset-api/models"
    "github.com/ONSdigital/dp-dataset-api/sdk"
)

headers := sdk.Headers{
    AccessToken: "example-auth-token",
    IfMatch: "ETag"
}

metadataToUpdate := models.EditableMetadata{
    Title: "The dataset title",
    Description: "A description of the dataset",
    // populate other required fields as required
}

err := client.PutMetadata(ctx, headers, "dataset-id", "edition-id", "1", metadataToUpdate)

PutVersion

import (
    "github.com/ONSdigital/dp-dataset-api/models"
    "github.com/ONSdigital/dp-dataset-api/sdk"
)

headers := sdk.Headers{
    AccessToken: "example-auth-token",
}

versionToUpdate := models.Version{
    Type: models.Static.String(),
    EditionTitle: "Updated Edition Title",
    // populate other required fields as required
}

updatedVersion, err := client.PutVersion(ctx, headers, "dataset-id", "edition-id", "1", versionToUpdate)

PutVersionState

import (
    "github.com/ONSdigital/dp-dataset-api/models"
    "github.com/ONSdigital/dp-dataset-api/sdk"
)

headers := sdk.Headers{
    AccessToken: "example-auth-token",
}

// Example to change to "approved" state
err := client.PutVersionState(ctx, headers, "dataset-id", "edition-id", "1", models.ApprovedState)

PostVersion

import "github.com/ONSdigital/dp-dataset-api/sdk"

headers := sdk.Headers{
    AccessToken: "example-auth-token",
}

versionToCreate := models.Version{
    Type:         models.Static.String(),
    Edition:      "edition-id",
    EditionTitle: "Edition Title",
    // populate other required fields as required
}

// Pass true to set this version as the latest version at series level
createdVersion, err := client.PostVersion(ctx, headers, "dataset-id", "edition-id", "1", versionToCreate, true)

Additional Information

Errors

The dataset-api has multiple formats of which errors can be returned such as a plaintext string or a more informative ErrorResponse. The SDK will return an error object which will contain the string of the error returned from the API. This could be used to string search for a specific status code or message for handling within an external service.

Headers

The Headers struct allows the user to provide headers for a request. An example of setting an "Authorization" header can be seen in the Example usage of client section.

Available headers

QueryParams

The QueryParams struct allows the user to provide query parameters if required. This is shown in the GetVersions example. The options include IDs, IsBasedOn, State, Limit and Offset.

Mocks

To simplify testing, all functions provided by the client have been defined in the Clienter interface. This allows the user to use auto-generated mocks within unit tests.

Example of how to define a mock clienter:

import (
    "context"
    "testing"

    "github.com/ONSdigital/dp-dataset-api/models"
    "github.com/ONSdigital/dp-dataset-api/sdk"
    "github.com/ONSdigital/dp-dataset-api/sdk/mocks"
)

func Test(t *testing.T) {
    mockClient := mocks.ClienterMock{
        GetDatasetFunc: func(ctx context.Context, headers sdk.Headers, datasetID string) (models.Dataset, error) {
            // Setup mock behaviour here
            return models.Dataset{}, nil
        },
        // Other methods can be mocked if needed
    }
}