Contents x
      FieldData API in Wasabi AiR
      • 22 Aug 2024
      • 10 Minutes to read
      • Print
      • PDF
      Contents

      FieldData API in Wasabi AiR

      • Updated on 22 Aug 2024
      • 10 Minutes to read
      • Print
      • PDF
      Article summary

      The FieldData API enables users to view, add, or delete values for an item’s custom fields. Individual values for the item and field can be specified as well as lists of various items and their various, corresponding fields.

      Getting the Value Stored for a Single Field on an Item

      GET /api/data/v3/fielddata/{item_id}/field/{field_id}

      • {item_id} - (string) The ID of the item for which to get the value.

      • {field_id} - (string) The ID of the specific field for which to get the value.

      Response

      {
  "fielddata_id": "378dbeba04af4325d7caea758f8eb570",
  "field_id": "d7caea758f8eb570ff90f1ef09c0da3",
  "field_name": "A boolean field",
  "field_datatype": "bool",
  "value": {
    "bool_value": true
  }
}

      Response attributes:

      • fielddata_id - The ID of this particular stored value.

      • field_id - The ID of the field for which the value is stored.

      • field_name - The name of the field for which the value is stored.

      • field_datatype - Datatype of the field for which the value is stored. Possible options are bool, date, number, and string.

      • value- Actual values stored for the field on this item. Up to four possible options may be returned, although the only valid option is the one that corresponds to the field datatype.

        • bool_value (optional) - True or false.

        • date_value (optional) - Date value in the YYYY-MM-DD format.

        • numeric_value (optional) - A number that allows for decimal point usage.

        • string_value (optional) - A string of characters.

      Values other than the one corresponding to the datatype may be returned. These should be ignored. The only value that should be displayed or used is one that corresponds to the actual datatype of the field. Do not use the date value of the field if it is of a string datatype.

      Status codes:

      • 200 (success)

      • 400 (bad request) status is returned if the {item_id} is not provided.

      • 400 (bad request) status is returned if the {field_id} is not provided.

      • 500 (unexpected error) status may be returned if unexpected errors happen in the process of fulfilling this request.

      Getting All fielddata for an Item

      GET /api/data/v3/fielddata/{item_id}

      • {item_id} - (string) The ID of the item for which to get fielddata values.

      Response

      {
  "item_id": "8c82f91176783e2cf90f945c76b7b7b2",
  "fields": [
    {
      "fielddata_id": "378dbeba04af4325d7caea758f8eb570",
      "field_id": "d7caea758f8eb570ff90f1ef09c0da3",
      "field_name": "A boolean field",
      "field_datatype": "bool",
      "value": {
        "bool_value": true
      }
    },
    {
      "fielddata_id": "ff90f1ef09c0da3658015489f752d0c0",
      "field_id": "bebca15a647065cfd6f69aacaf1abdb",
      "field_name": "A date field",
      "field_datatype": "date",
      "value": {
        "date_value": "2020-01-06T13:02:29.385799Z"
      }
    },
    {
      "fielddata_id": "6c59f9ea0af180266bebca15a647065c",
      "field_id": "fd6f69aacaf1abdbd6c59f9ea0af180",
      "field_name": "A numeric field",
      "field_datatype": "number",
      "value": {
        "numeric_value": 1.23456
      }
    },
    {
      "fielddata_id": "fd6f69aacaf1abdbd4f8cba8006965f8",
      "field_id": "ff90f1ef09c0da37caea758f8eb570c",
      "field_name": "A string field",
      "field_datatype": "string",
      "value": {
        "string_value": "abcdefg"
      }
    }
  ]
}

      Response attributes:

      • item_id - The ID of the item requested.

      • fields- A list of fields that have values set for them on this item.

        • fielddata_id - The ID of the particular stored value.

        • field_id - The ID of the field for which the value is stored.

        • field_name - The name of the field for which the value is stored.

        • field_datatype - The datatype of the field for which the value is stored. Possible options are bool, date, number, and string.

        • value - The actual values stored for the field on this item. Up to four possible options may be returned, although the only valid option is the one that corresponds to the field datatype.

        • bool_value (optional) - True or false.

        • date_value (optional) - Date value in the YYYY-MM-DD format.

        • numeric_value (optional) - A number that allows for decimal point usage.

        • string_value (optional) - A string of characters.

      Values other than the one corresponding to the datatype may be returned. These should be ignored. The only value that should be displayed or used is one that corresponds to the actual datatype of the field. Do not use the date value of the field if it is of a string datatype.

      Status codes:

      • 200 (success)

      • 400 (bad request) status is returned if the {item_id} is not provided.

      • 500 (unexpected error) status may be returned if unexpected errors happen in the process of fulfilling this request.

      Creating a Value for a Single Boolean Field on an Item

      POST /api/data/v3/fielddata/{item_id}/field/{field_id}
{
  "bool_value" : true
}

      • {item_id} - (string) The ID of the item for which to get the value.

      • {field_id} - (string) The ID of the specific field to which to get the value.

      • bool_value - Either true or false.

      Response

      {
  "fielddata_id": "d168b202a0ea8e8379e8c2384623b8c8",
  "field_id": "d7caea758f8eb570ff90f1ef09c0da3",
  "field_name": "A boolean field",
  "field_datatype": "bool",
  "value": {
    "bool_value": true
  }
}

      Status codes:

      • 201 (created)

      • 400 (bad request) status is returned if the {item_id} is not provided.

      • 400 (bad request) status is returned if the {field_id} is not provided.

      • 404 (not found) status is returned if the provided {item_id} does not exist.

      • 404 (not found) status is returned if the provided {field_id} does not exist.

      • 500 (unexpected error) status may be returned if unexpected errors happen in the process of fulfilling this request.

      Value is not returned if the bool_value was set to false.

      Creating a Value for a Single Date Field on an Item

      POST /api/data/v3/fielddata/{item_id}/field/{field_id}
{
  "date_value" : "2020-12-25"
}

      • {item_id} - (string) The ID of the item for which to get the value.

      • {field_id} - (string) The ID of the specific field for which to get the value.

      • date_value - A value in the format YYYY-MM-DD.

      Response

      {
  "fielddata_id": "d168b202a0ea8e8379e8c2384623b8c8",
  "field_id": "bebca15a647065cfd6f69aacaf1abdb",
  "field_name": "A date field",
  "field_datatype": "date",
  "value": {
    "date_value": "2020-12-25T00:00:00Z",
  }
}

      Status codes:

      • 201 (created)

      • 400 (bad request) status is returned if the {item_id} is not provided.

      • 400 (bad request) status is returned if the {field_id} is not provided.

      • 404 (not found) status is returned if the provided {item_id} does not exist.

      • 404 (not found) status is returned if the provided {field_id} does not exist.

      • 500 (unexpected error) status may be returned if unexpected errors happen in the process of fulfilling this request.

      Creating a Value for a Number String Field on an Item

      POST /api/data/v3/fielddata/{item_id}/field/{field_id}
{
  "numeric_value" : 1.2345
}

      • {item_id} - (string) The ID of the item for which to get the value.

      • {field_id} - (string) The ID of the specific field for which to get the value.

      Response

      {
  "fielddata_id": "d168b202a0ea8e8379e8c2384623b8c8",
  "field_id": "ff90f1ef09c0da37caea758f8eb570c",
  "field_name": "A numeric field",
  "field_datatype": "number",
  "value": {
    "numberic_value": 1.2345
  }
}

      Status codes:

      • 201 (created)

      • 400 (bad request) status is returned if the {item_id} is not provided.

      • 400 (bad request) status is returned if the {field_id} is not provided.

      • 404 (not found) status is returned if the provided {item_id} does not exist.

      • 404 (not found) status is returned if the provided {field_id} does not exist.

      • 500 (unexpected error) status may be returned if unexpected errors happen in the process of fulfilling this request.

      Creating a Value for a Single String Field on an Item

      POST /api/data/v3/fielddata/{item_id}/field/{field_id}
{
  "string_value" : "abcde FG"
}

      • {item_id} - (string) The ID of the item to which to the get value.

      • {field_id} - (string) The ID of the specific field to which to get the value.

      Response

      {
  "fielddata_id": "d168b202a0ea8e8379e8c2384623b8c8",
  "field_id": "ff90f1ef09c0da37caea758f8eb570c",
  "field_name": "A string field",
  "field_datatype": "string",
  "value": {
    "string_value": "abcde FG"
  }
}

      Status codes:

      • 201 (created)

      • 400 (bad request) status is returned if the {item_id} is not provided.

      • 400 (bad request) status is returned if the {field_id} is not provided.

      • 404 (not found) status is returned if the provided {item_id} does not exist.

      • 404 (not found) status is returned if the provided {field_id} does not exist.

      • 500 (unexpected error) status may be returned if unexpected errors happen in the process of fulfilling this request.

      Updating Fields

      Single field update requests and responses are the same as those for creating a value with the exception that the request method is a PUT instead of a POST, and the success status code is a 200 instead of a 201 created status code.

      Deleting a Value for a Single Boolean Field on an Item

      DELETE /api/data/v3/fielddata/{item_id}/field/{field_id}

      • {item_id} - (string) The ID of the item for which to get the value.

      • {field_id} - (string) The ID of the specific field to which to get the value.

      Response

      {
  "fielddata_id": "6c59f9ea0af180266bebca15a647065c",
  "field_id": "fd6f69aacaf1abdbd6c59f9ea0af180",
  "field_name": "A number value",
  "field_datatype": "number",
  "value": {
    "numeric_value": 1.23456
  }
}

      The deleted field value is returned.

      Status codes:

      • 200 (success)

      • 500 (unexpected error) status may be returned if unexpected errors happen in the process of fulfilling this request.

      Updating Many Items and Field Values at Once

      This API allows for setting varying values on many items at once. The values being updated need not have been previously set. Only specified fields are updated, unspecified fields are unaffected. A maximum of 1,000 updates field values can be set at once. This limit can be reached when updating 1,000 items with a single field a piece or 10 items with 100 fields a piece. No URL arguments are required.

      PUT /api/data/v3/fielddata
[
  {
    "item_id": "8c82f91176783e2cf90f945c76b7b7b2",
    "fields": [
      {
          "field_id": "d7caea758f8eb570ff90f1ef09c0da3",
          "value": {
              "bool_value": true
          }
      },
      {
          "field_id": "bebca15a647065cfd6f69aacaf1abdb",
          "value": {
              "date_value": "1983-03-07"
          }
      },
      {
          "field_id": "fd6f69aacaf1abdbd6c59f9ea0af180",
          "value": {
              "numeric_value": 459.1
          }
      }
    ]
  },
  {
    "item_id": "2b7b7b67c549f09fc2e38767119f28c8",
    "fields": [
      {
          "field_id": "bebca15a647065cfd6f69aacaf1abdb",
          "value": {
              "date_value": "1995-06-12"
          }
      },
      {
          "field_id": "fd6f69aacaf1abdbd6c59f9ea0af180",
          "value": {
              "numeric_value": 600.25
          }
      },
      {
          "field_id": "ff90f1ef09c0da37caea758f8eb570c",
          "value": {
              "string_value": "Pump Panel Confusion"
          }
      }
    ]
  }
]

      Response

      {
  "changed": [
    {
        "item_id": "8c82f91176783e2cf90f945c76b7b7b2",
        "fields": [
          {
            "fielddata_id": "378dbeba04af4325d7caea758f8eb570",
            "field_id": "d7caea758f8eb570ff90f1ef09c0da3",
            "value": {
              "bool_value": true
            }
          },
          {
            "fielddata_id": "ff90f1ef09c0da3658015489f752d0c0",
            "field_id": "bebca15a647065cfd6f69aacaf1abdb",
            "value": {
              "date_value": "1983-03-07T00:00:00Z"
            }
          },
          {
            "fielddata_id": "6c59f9ea0af180266bebca15a647065c",
            "field_id": "fd6f69aacaf1abdbd6c59f9ea0af180",
            "value": {
              "numeric_value": 459.1
            }
          }
        ]
    },
    {
      "item_id": "2b7b7b67c549f09fc2e38767119f28c8",
      "fields": [
        {
          "fielddata_id": "ff90f1ef09c0da3658015489f752d0c0",
          "field_id": "bebca15a647065cfd6f69aacaf1abdb",
          "value": {
            "date_value": "1983-03-07T00:00:00Z"
          }
        },
        {
          "fielddata_id": "6c59f9ea0af180266bebca15a647065c",
          "field_id": "fd6f69aacaf1abdbd6c59f9ea0af180",
          "value": {
            "numeric_value": 459.1
          }
        },
        {
          "fielddata_id": "15a647065cfd6f695a6c59f9ea0af18",
          "field_id": "ff90f1ef09c0da37caea758f8eb570c",
          "value": {
            "string_value": "Pump Panel Confusion"
          }
        }
      ]
    }
  ]
}

      Status codes:

      • 200 (success)

      • 500 (unexpected error) status may be returned if unexpected errors happen in the process of fulfilling this request.

      Erroneous Items and Fields Specified

      When a given item or field ID turns out to be invalid, a list is provided in the response stating the ID. This does not cause the entire request to be rejected, as correctly stated IDs are updated accordingly.

      Response

      {
  "invalid_items": ["NON-EXISTENT-ITEMID"],
  "invalid_fields": ["NON-EXISTENT-FIELDID"],
}

      Status codes:

      • 200 (success) should be expected, since only an internal server error would prevent updates to good combinations of item and field IDs.

      • 500 (unexpected error) status may be returned if unexpected errors happen in the process of fulfilling this request.



      What's Next
      Copyright © 2024 by Wasabi Technologies LLC
      75 Arlington Street, Suite 810, Boston, MA 02116 USA
      All Rights Reserved
      Visit us at https://wasabi.com.
      WASABI and the WASABI logo are trademarks of Wasabi Technologies LLC and may not be used without permission of Wasabi Technologies. All other names are used for identification purposes only and are trademarks or registered trademarks of their respective companies.

      Information presented herein is subject to change without notice. Companies, names, and data used in examples are fictitious unless otherwise noted. No part of this information may be reproduced or transmitted in any form by means electronic or mechanical, for any purpose, without express written permission of Wasabi Technologies.