Table of contents

FieldData API

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

Get the value stored for a single field on an item

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

• {item_id} - (string) ID of Item to get value for.
• {field_id} - (string) ID of the specific Field to get the value for.

Response

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

Response attributes:

• fielddata_id - id this particular stored value
• field_id - id of the field for which the value is stored
• field_name - 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, though 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 ‘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 to be ignored. The only value that should be displayed or used should is one that corresponds to the actual datatype of the field, ie., don’t use the date value of the field is of a string datatype.

Status codes:

• 200 (success)
• 400 (bad request) status will be returned if the {item_id} is not provided.
• 400 (bad request) status will be 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.

Get all fielddata for an item

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

• {item_id} - (string) ID of Item to get fielddata values for.

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 - list of fields which have values set for them on this item
  • fielddata_id - id this particular stored value
  • field_id - id of the field for which the value is stored
  • field_name - 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, though 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 ‘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 to be ignored. The only value that should be displayed or used should is one that corresponds to the actual datatype of the field, ie., don’t use the date value of the field is of a string datatype.

Status codes: * 200 (success) * 400 (bad request) status will be 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) ID of Item to get value for.
• {field_id} - (string) ID of the specific Field to get the value for.

Where the bool_value is 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 will be returned if the {item_id} is not provided. * 400 (bad request) status will be returned if the {field_id} is not provided. * 404 (not found) status will be returned if the provided {item_id} does not exist. * 404 (not found) status will be 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 will not be 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) ID of Item to get value for.
• {field_id} - (string) ID of the specific Field to get the value for.

Where date_value is 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 will be returned if the {item_id} is not provided. * 400 (bad request) status will be returned if the {field_id} is not provided. * 404 (not found) status will be returned if the provided {item_id} does not exist. * 404 (not found) status will be 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) ID of Item to get value for.
• {field_id} - (string) ID of the specific Field to get the value for.

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 will be returned if the {item_id} is not provided. * 400 (bad request) status will be returned if the {field_id} is not provided. * 404 (not found) status will be returned if the provided {item_id} does not exist. * 404 (not found) status will be 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) ID of Item to get value for.
• {field_id} - (string) ID of the specific Field to get the value for.

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 will be returned if the {item_id} is not provided. * 400 (bad request) status will be returned if the {field_id} is not provided. * 404 (not found) status will be returned if the provided {item_id} does not exist. * 404 (not found) status will be 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 updates 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 will be 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) ID of Item to get value for.
• {field_id} - (string) ID of the specific Field to get the value for.

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.

Upserting many items and field values at once

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 updated 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

In case that a given item or field ID turns out to be invalid, a list will be provided in the response stating the ID. This will not cause the entire request to be rejected, as correctlys stated ID’s will be updated accordingly.

{
    {
      "item_id": "NON-EXISTENT-ITEMID",
      {
          "field_id": "NON-EXISTENT-FIELDID",
          "value": {
              "string_value": "abcdefg"
          }
      },
    }
}

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.

This documentation is generated from the latest version of GrayMeta Platform. For documentation relevant to your own deployed version, please use the documentation inside the application.

© 2021 GrayMeta, Inc.