DDB Documentation

# Migration to v1

This guide explains how to migrate from v0 to v1, for the affected microservices.

# Changes across the services

# Querying for deleted items

GET endpoints that allow return of deleted items now have the following queries available:

  • show_active - a boolean flag (default true) to return non-deleted (i.e. active) items in the response body
  • show_deleted - a boolean flag (default false) to return deleted items in the response body.

By default, active items will be returned only.

To return deleted items only, request with show_deleted value true and show_active value false.

To return both active and deleted items, request with show_deleted value true.

Note: some endpoints contain the show_deleted query only, but the behaviour is the same.

# Pagination

Pagination has been added to several routes across the services. This is so large responses can be managed reasonably.

Pagination adds new queries to any paginated endpoints:

+ ?page_limit=int
+ ?before=base64
+ ?after=base64

Where not present before, new queries of order and sort_by will also be present on paginated endpoints:

+ ?sort_by=name
+ ?order=desc

Please see the documentation for more information on these queries.

The response bodies for paginated endpoints have also been updated with new keys:

+ paging: {
+     cursors: {
+       before: "MjUxYjYzNzAtNDk1MC1lNzExLTgxMDQtMDA1MDU2YjU3NDU5",
+       after: "OGExMTcxNzAtNDk1MC1lNzExLTgxMDQtMDA1MDU2YjU3NDU5"
+     },
+     previous: "http://ddb.arup.com/api/projects?before=MjUxYjYzNzAtNDk1MC1lNzExLTgxMDQtMDA1MDU2YjU3NDU5",
+     next: "http://ddb.arup.com/api/projects?after=MjUxYjYzNzAtNDk1MC1lNzExLTgxMDQtMDA1MDU2YjU3NDU5"
+   },
+   summary: {
+     estimate_count: 44
+  }

# Error messages

Client error responses no longer include the source key:

  {
    details: "id \"632f6133-c5c4-4232-bdb6-c1a227a48b8e\" could not be found",
    msg: "Route Not Found",
-   source: "body"
  }

# Parameter Service

Please use these migration notes to help switch from v0 of the parameter-service-api to v1. This section should detail all the changes across the versions.

# Deprecated Endpoints

The following endpoints have been removed from v1:

# **GET /parameters/:parameter_id/revision**

replaced by new endpoint GET /entries/:entry_id/revisions (see below)

# **POST /parameters/:parameter_id/revision**

replaced by new endpoint PUT /entries (see below)

# **PATCH /parameters/:parameter_id/revision**

replaced by new endpoint PATCH /revisions (see below)

# Changes across endpoints

Please see below for the changes to each endpoint. This is structured in a similar way to the API documentation (opens new window) for ease of use.

Note: not all endpoints have had changes.

# Assets

# GET /assets

  • Pagination added. Please see the beginning section for more information.

  • Response body now includes asset_type_id property in the asset_sub_type key:

    asset_sub_type: {
      id: "a7154e9a-9dd4-4983-a900-c172a3366544",
      name: "Domestic Hot Water",
+     asset_type_id: "577cfd8d-8da0-4d78-b4a4-c81ab728d4bf",
      parent_asset_sub_type_id: "f2ac4d11-6854-4763-b26e-2b2c664390cb"
    }

  • The show_deleted_assets query has been replaced. Please see above section for more information

    - GET /assets?show_deleted_assets=true
+ GET /assets?show_deleted=true

# POST /assets

  • This endpoint now accepts one of asset_type_id OR asset_sub_type_id in the request body:

    • If you are providing asset_sub_type_id then the name field is optional and if left blank will be populated automatically to match the asset_sub_type name.
    • If you provide an asset_type_id only for an asset that has asset_sub_type property of true, you will receive an error if posting with a name property not matching one of the valid sub type names.

  • The response body now includes asset_type_id property in the asset_sub_type key:

    asset_sub_type: {
      id: "a7154e9a-9dd4-4983-a900-c172a3366544",
      name: "Domestic Hot Water",
+     asset_type_id: "577cfd8d-8da0-4d78-b4a4-c81ab728d4bf",
      parent_asset_sub_type_id: "f2ac4d11-6854-4763-b26e-2b2c664390cb"
    }

# GET /assets/{asset_id}

  • The response body now includes asset_type_id property in the asset_sub_type key:

    asset_sub_type: {
      id: "a7154e9a-9dd4-4983-a900-c172a3366544",
      name: "Domestic Hot Water",
+     asset_type_id: "577cfd8d-8da0-4d78-b4a4-c81ab728d4bf",
      parent_asset_sub_type_id: "f2ac4d11-6854-4763-b26e-2b2c664390cb"
    }

  • The show_deleted_assets query has been replaced. Please see the above section for more information

    - GET /assets?show_deleted_assets=true
+ GET /assets?show_deleted=true

# GET /assets/{asset_ids}/hierarchy

  • Each hierarchy object in the response body now includes an asset_type_id key:

    {
  hierarchies: [
    [
      {
        id: "a3d5c386-9451-495e-9d3c-8ed152b1300f",
        name: "Wellington Place",
+       asset_type_id: "a3d5c386-9451-495e-9d3c-8ed152b1300f"
      }
    ]
  ]
}

# Entries

An entry represents a value for a parameter. Entries can be revised. Currently, parameters are restricted to maximum of one entry. In future versions, parameters will have the capacity to have multiple entries. Please see the documentation (opens new window) for more information.

There are four new routes relating to entries:

# GET /entries

  • This endpoint returns all entries, this is queryable by an array of parameter_id's.

# PUT /entries

  • This endpoint replaces POST /parameters/:parameter_id/revision and lets you create or update one or more entries.

  • This endpoint accepts an array of entries. Required fields are entry_id, parameter_id, source_id, values. Currently, values has a maximum length of one. Optional additions are comment and location_in_source.

# GET /entries/:entry_id/revisions

  • This endpoint replaces GET /parameters/:parameter_id/revision, and returns all revisions for a specified entry_id.

# PATCH /revisions

  • This endpoint replaces the PATCH /parameters/:parameter_id/revisions endpoint and allows users to update the status of multiple revisions related to multiple different entries at once.
    • Users should only update the latest revision of an entry
    • Users are required to specify the revision_id of the revision to update
    • If users are updating the revision status to QA state rejected a comment property is required.

# Parameter Sets

Note: Parameter Sets are in ALPHA release for testing. It is not recommended to use these routes in production.

The naming conventions for Parameter Sets has been altered from v0 to v1. Changes are as follows:

v0 naming convention v1 naming convention
parameter_set_type parameter_set_category
parameter_set parameter_set_type
parameter_set_instance parameter_set

This has resulted in the update of routes in the following way:

v0 route v1 route
GET /parameter_set_types GET /parameter_set_categories
GET /parameter_sets GET /parameter_set_types
POST /parameter_sets POST /parameter_set_types
DELETE /parameter_sets/:parameter_set_id DELETE /parameter_set_types/:parameter_set_type_id
POST /parameter_sets/:parameter_set_id/items POST /parameter_set_types/:parameter_set_type_id/items
DELETE //parameter_sets/:parameter_set_id/items/:item_type_id DELETE /parameter_set_types/:parameter_set_type_id/items/:item_type_id
GET /parameter_sets/:parameter_set_id/instances GET /parameter_sets
GET /parameter_sets/:parameter_set_id/instances/:instance_id GET /parameter_sets/:parameter_set_id
GET /parameter_sets/:parameter_set_id/instances/:instance_id/parameters GET /parameter_sets/:parameter_set_id/parameters

The keys on the response bodies have been updated in the relevant way. For example a request to GET /parameter_set_categories (previously known as GET /parameter_set_types) will return a response with:

{
-   parameter_set_types: [ ... ]
+   parameter_set_categories: [ ... ]
}

All endpoints should behave in a similar way (excluding endpoints detailed below).

# GET /parameter_sets

This endpoint replaces v0 endpoint GET /parameter_sets/:parameter_set_id/instances. To filter parameter sets by the relevant parameter_set_type_id this is passed in through a query on the endpoint:

+ GET /parameter_sets?parameter_set_type_id=uuid

This will return all parameter_sets of the specified parameter_set_type_id.

# GET /parameter_sets/:parameter_set_id/parameters

This endpoint contains a reduced response compared to the v0 version (GET /parameter_sets/:parameter_set_id/instances/:instance_id/parameters):

{
- parameter_set_instance_parameters: [
+  parameter_set_parameters: [
    {
      ...parameter,
      parameter_type: {
        id,
        name,
        data_type,
        global_parameter,
-       unit_type_id,
-       created_at,
-       deleted_at,
-       updated_at
      },
      parents: [
        {
          id,
          asset_sub_type,
          children,
          name,
          parent,
          asset_type: {
            id,
            name,
            parent_id,
-           asset_sub_type,
-           asset_type_group,
-           created_at,
-           deleted_at,
          },
-         project_id,
-         deleted_at,
        }
      ]
    }
  ],
  ... rest
}

# Parameters

# GET /parameters

  • Pagination added. Please see the beginning section for more information.

  • The show_deleted_parameters query has been replaced. Please see the above section for more information

    - GET /parameters?show_deleted_parameters=true
+ GET /assets?show_deleted=true

  • The offset query has been removed:

    - GET /parameters?offset=

  • The revision key in the response body has been renamed to selected_entry:

    {
  parameters: [
    {
      ... parameter,
-    revision: { ... }
+     selected_entry: { ... }
    },
    ...
  ]
}

  • The selected_entry.source key contains a reduced response

    source: {
        id: "286a550e-00bc-4b1e-8e20-71f96b43e9c6",
        created_at: "2022-07-18T16:00:53.182Z",
-         updated_at: "2022-07-18T16:00:53.182Z",
-         deleted_at: null,
-         time: null,
        date_day: "15",
        date_month: "1",
        date_year: "2021",
        reference: "Assumption",
-         reference_id: "90803033-268a-ea11-8129-005056b50c57",
-         reference_table: "project",
-         reference_url: "dev.ddb.arup.com/api/project",
-         scope: "90803033-268a-ea11-8129-005056b50c57",
        title: "Assumption",
        url: "TBA",
        source_type: {
          id: "6a1292c7-a245-41cf-8872-46feb9a7fd11",
          name: "Assumption",
-           visible: true,
-           deleted_at: null
        }
      }

  • The selected_entry.created_by key contains a reduced response

    created_by: {
-         staff_id: 12345,
        staff_name: "Arup Employee Name",
        email: "[email protected]",
-         company_centre_arup_unit: "01-462 NOR Digital Services",
-         location_name: "Edinburgh Office",
-         grade_level: 3,
-         my_people_page_url: "https://arup-my.sharepoint.com/PersonImmersive.aspx?accountname=i:0%83.f%7cmembership%[email protected]"
},

  • The selected_entry key does not have an updated_at, comment or location_in_source property.

# POST /parameters

  • The revision key in the request body has been replaced with entries, which accepts an array.
    • There is an optional entry_id key in the entries post body:
      • If you are adding a NEW entry to an unanswered parameter, this can be left empty and will automatically populate with an new uuid.
      • If you are wanting to REVISE an answered parameter, you must provide the existing entry_id to revise.

This is currently limited to one item in the entries property only.

  • The revision key in the POST response body is now renamed to selected_entry
    - revision: { ... }
+ selected_entry: { ... }

# GET /parameters/{parameter_id}

  • The show_deleted_parameters query has been replaced. Please see the above section for more information

    - GET /parameters/:parameter_id?show_deleted_parameters=true
+ GET /parameters/:parameter_id?show_deleted=true

  • The revision key in the response body has been renamed to selected_entry

    - revision: { ... }
+ selected_entry: { ... }

  • The selected_entry.source key contains a reduced response

    source: {
        id: "286a550e-00bc-4b1e-8e20-71f96b43e9c6",
        created_at: "2022-07-18T16:00:53.182Z",
-         updated_at: "2022-07-18T16:00:53.182Z",
-         deleted_at: null,
-         time: null,
        date_day: "15",
        date_month: "1",
        date_year: "2021",
        reference: "Assumption",
-         reference_id: "90803033-268a-ea11-8129-005056b50c57",
-         reference_table: "project",
-         reference_url: "dev.ddb.arup.com/api/project",
-         scope: "90803033-268a-ea11-8129-005056b50c57",
        title: "Assumption",
        url: "TBA",
        source_type: {
          id: "6a1292c7-a245-41cf-8872-46feb9a7fd11",
          name: "Assumption",
-           visible: true,
-           deleted_at: null
        }
      }

  • The selected_entry.created_by key contains a reduced response

    created_by: {
-         staff_id: 12345,
        staff_name: "Arup Employee Name",
        email: "[email protected]",
-         company_centre_arup_unit: "01-462 NOR Digital Services",
-         location_name: "Edinburgh Office",
-         grade_level: 3,
-         my_people_page_url: "https://arup-my.sharepoint.com/PersonImmersive.aspx?accountname=i:0%83.f%7cmembership%[email protected]"
},

  • The selected_entry key does not have an updated_at, comment or location_in_source property.

# Tree

There are several new endpoint to return tree hierarchies. Please see the documentation (opens new window) for more information on these endpoints.

# GET /asset_tree

  • New endpoint that returns an asset tree by asset_id.

# GET /asset_type_tree

  • New endpoint that returns an asset type tree by asset_type_id.

# Types

# GET /asset_type_groups

# GET /asset_types

# GET /asset_types/{asset_type_id}/asset_sub_types

# GET /parameter_types

  • Pagination added. Please see the beginning section for more information.

  • The name key on the default_unit property in the response body has been renamed to symbol:

    default_unit: {
      id: "b39e5bcf-cda6-49ed-8c0c-174d8daf8bc1",
-     name: "°C",
+     symbol: "°C",
      unit_type_id: "5391cd71-08f0-44f8-9dd2-6379a511dd29",
      unit_system_id: "50115948-140f-48fc-b5f2-c56e96869734"
      }

# GET /item_types

  • Pagination added. Please see the beginning section for more information.

  • The offset query has been removed.

# GET /unit_types

  • Pagination added. Please see the beginning section for more information.

  • Each unit_type object has a new unit_systems key, containing the unit systems and units that are available to that particular type

    unit_types: [
{
id: "e8c3da00-5c20-45f1-a24c-0d657bcae032",
name: "Geotechnics analysis material type",
created_at: "2022-06-24T12:26:00.263Z",
updated_at: "2022-06-24T12:26:00.263Z",
deleted_at: null,
+ unit_systems: [
+  {
+    id: "5508a780-9f9f-4e6d-bc9c-a84607a5ba87",
+    name: "Drop-down list",
+    short_name: "Drop-down",
+    units: [
+      {
+        id: "892c32c1-808a-440a-8290-e05fdf5457ba",
+        symbol: "Mohr-coulomb, linear-elastic"
+      }
+    ]
+  }
+ ]
}
]

# POST /unit_types

  • The unit_types response body for the POST method has been updated in the same way as the GET /unit_types - please refer to this section for details.

# GET /unit_types/:unit_type_id

  • The unit_type object response body now includes created_at, updated_at and deleted_at keys:
unit_type: {
    id: "38f045f3-ce7a-4a38-9fe7-f9d72d07a129",
    name: "Area",
+   created_at: "2021-12-22T13:07:17.214Z",
+   updated_at: "2021-12-22T13:07:17.214Z",
+   deleted_at: null,
    unit_systems: [ ... ]
  }

# Units

# GET /units

  • Pagination added. Please see the beginning section for more information.

  • The name key in the response body has been renamed to symbol:

    {
  id: "a3d5c386-9451-495e-9d3c-8ed152b1300f",
  created_at: "2019-05-10T13:45:08.000Z",
  deleted_at: "2020-06-18T11:25:21.000Z",
- name: "m",
+ symbol: "m",
  updated_at: "2020-06-12T13:39:41.000Z",
  unit_type_id: "7a857f03-a222-405c-bc03-90d6dcaa8e0e",
  unit_system_id: "50115948-140f-48fc-b5f2-c56e96869734"
}

# POST /units

  • The request body no longer accepts a name field. This should now be symbol:

    {
  id: "cdbcb4d1-b6c1-436c-8126-737c29c9b2f4",
- name: "°F",
+ symbol: "°F",
  unit_type_id: "b68caf97-e537-4ce4-b3bd-7131f0e72e93",
  unit_system_id: "50115948-140f-48fc-b5f2-c56e96869734"
  }

# GET /unit_systems

# Parameter Metadata Service

Please use these migration notes to help switch from v0 of the parameter-metadata-service-api to v1. This document should detail all the changes across the versions.

# Deprecated Endpoints

Please note that all endpoints in v0 of the API are being deprecated so users must upgrade to the next available version

# Changes across endpoints

Please see below for the changes to each endpoint. This is structured in a similar way to the API documentation (opens new window) for ease of use.

Note: not all endpoints have had changes.

# Allow Custom

  • allow_custom is a new key in the response body for all tag_type objects returned endpoints. This property signifies if a tag_type accepts custom tags or not using a boolean value of true or false.

    tag_type: {
        id: "1e08965a-f116-4a6d-8bba-74290edc8c0a",
        created_at: "2019-05-10T13:45:08.000Z",
        deleted_at: "2019-05-10T13:45:08.000Z",
        name: "Calculation",
        updated_at: "2019-05-10T13:45:08.000Z",
+       allow_custom: false
      }

# Tag

# GET /tags

  • Pagination added. Please see the beginning section for more information.

  • New queries added for retrieving deleted tags. Please see above section for more information.

  • The item_limit query has been replaced by the page_limit query as part of pagination.

  • There is a new query available for tag_scope, this can be one or more project_id's and will return all tags with the given tag_scope. An empty (null) query string filters for all tags with no scope, i.e. global tags.

  • There is a new query available for omit_global (bool). If true, this omits all global tags (those with tag_scope = null) from the result. The default value for this query is false.

  • The tag_type object in the response body for a tag now includes a new key of allow_custom. Please see this section for more information.

# POST /tags

  • This is a new endpoint that allows users to add a new tag.
  • Any user can post a custom tag that is scoped to a project (i.e. a tag that has tag_type with property allow_custom: true and tag_scope: your-project-uuid). Posting global tags requires Admin privileges.

# GET /tags/:tag_id

  • The tag_type object in the response body now includes a new key of allow_custom. Please see this section for more information.

# PATCH /tags/:tag_id

  • This is a new endpoint that allows you to update a tag name property.
  • This endpoint requires Admin privileges.

# DELETE /tags/:tag_id

  • This is a new endpoint that allows you to delete a tag by tag_id.
  • This endpoint requires Admin privileges.

  • Pagination added. Please see the beginning section for more information.

  • New queries added for retrieving deleted tag links. Please see above section for more information.

  • This is a new endpoint for users to get an existing tag link between resources.
  • This is a new endpoint to update a links reference_table and/or reference_url between a tag and reference.
  • This is a new endpoint that allows users to put new and/or update existing tag_link's.

# Tag Type

# GET /tag_types

  • Pagination added. Please see the beginning section for more information.

  • New queries added for retrieving deleted tag types. Please see above section for more information.

  • The tag_type objects in the response body now include a new key of allow_custom. Please see this section for more information.

# POST /tag_types

  • This is a new endpoint that lets you add a new tag_type.
  • This endpoint requires Admin privileges.

# GET /tag_types/:tag_type_id

  • The tag_type object in the response body now include a new key of allow_custom. Please see this section for more information.

# PATCH /tag_types/{tag_type_id}

  • This is a new endpoint that allows users to updates a single tag_type.

Note: This endpoint requires admin privileges.

# DELETE /tag_types/{tag_type_id}
  • New endpoint that deletes a single tag type using the tag_type_id as a required query
  • This endpoint requires Admin privileges.

# Environment Context Service

Please use these migration notes to help switch from v0 of the Environmental-Context-Service-api to v1. This document should detail all the changes across the versions.

# Deprecated Endpoints

Please note that all endpoints in v0 of this API are being deprecated so users must upgrade to the next available version

Last Updated: 24/09/2024, 16:41:45

← Migration to v2 →