Announcing Our New API Endpoints and Error Responses

As we continue to provide a streamlined procedure to managing API connections and integrations we are excited to announce some new endpoints and updated error responses.

If you are a Developer or your organization's IT admin, please take a moment to review some of the improvements we made below. The following will be available on 2/20/23 for Train and 2/27/23 for Production.

New Endpoints

getFormsbyResource

In cases where you need to find all forms related to a resource, this can be done by searching the exact resource name. Some use cases include:

1. Finding all forms related to a resource to help find their definitions and update them
2. Build reports to view relationships between forms and resources to validate the right forms are associated with the right resources

getLocationsByResource

In cases where you need to find all locations associated to a resource, this can be done by searching by using the exact resource name, fuzzy search and by providing a list of resources. Some use cases include:

1. Finding all locations with their corresponding resources with all Unique IDs to keep data in sync if resource or location names change
2. Search and find all resources related to a location and search forms to verify all relationships are in sync

Get Image URL Functionality

Changes in the functionality of AllImageUrls as follows:

• When used, Image information will appear only if image info exists and only to the data row where the image exists
• Fields will have an additional column called FieldImageList which will contain images for the corresponding field

Old Data (getRecordFields)

  {
      "RecordNumber": "999999",
      "SubmittedDate": "2021-06-12T14:07:02+00:00",
      "FieldName": "\"Product of USA\" or \"Hatched, Raised, and Harvested in the USA\" is on the label as applicable?",
      "FieldShortName": "\"Product of USA\" or \"Hatc",
      "FieldType": "SelectOne",
      "FieldValue": "Yes",
      "ImageList": " https://tenant.stage.safetychain.com/AttachmentsStorage/tenant/7f4dbd50-9b30-4596-abae-7f4dbd50/0.png : https://tenant.stage.safetychain.com/AttachmentsStorage/tenant/7f4dbd50-9b30-4596-abae-7f4dbd50/28f1ac51-fe05-49a8-b854-28f1ac51/0.png",
      "Row": "20"
    }

New Data (getRecordFields)

    {
      "RecordNumber": "999999",
      "SubmittedDate": "2021-06-12T14:07:02+00:00",
      "FieldName": "\"Product of USA\" or \"Hatched, Raised, and Harvested in the USA\" is on the label as applicable?",
      "FieldShortName": "\"Product of USA\" or \"Hatc",
      "FieldType": "SelectOne",
      "FieldValue": "Yes",
      "ImageList": "https://tenant.stage.safetychain.com/AttachmentsStorage/tenant/7f4dbd50-9b30-4596-abae-7f4dbd50/0.png",
      "FieldImageList": "https://tenant.safetychain.com/AttachmentsStorage/tenant/7f4dbd50-9b30-4596-abae-7f4dbd50/28f1ac51-fe05-49a8-b854-28f1ac51/0.png",
      "Row": "20"
    }

Update to List Filters

For endpoints using ResourceList, LocationList, and FormList query parameters, users can now use pipe delimiters (|), to separate values to query. This will help in cases where your values include commas, for example a location may contain city and state with a comma - "Novato, CA|Sacramento,CA"; see example below.

{BaseURL}/API/rdTemplate/rdData.aspx?rdData=Records2&rdDataID=getRecords&LocationList=Novato,CA|Sacramento,CA

📘

Note:

If using pipe delimiters, no spaces can be used before or after the delimiter (unless its included in your query value) - "Novato,CA |" or "Novato,CA| Sacramento,CA"

In addition commas will still be operational for all list filters.

Updated Error Responses

Security Token Validation

If an invalid Security Token (ST) is used for authenticating the following response will be provided.

{
  "data": [
    {
      "ErrorMsg": "User Not Authorized"
    }
  ]
}

Throttling Threshold Validation

Based on your configured security token. For more details see Rate Limiting and Throttling

{
  "data": [
    {
      "ErrorMsg": "Rate limit exceeded (too many concurrent requests): Requests Allowed: 1 - Current Requests Open: 1"
    }
  ]
}

Date Range Validation/Record Number Validation

Based on the query parameters provided in all record requests, they must include a date or record filter this includes Start and End dates, MinAgo or Record Number.

{
  "data": [
    {
      "ErrorMsg": "Start Date, MinAgo or Record Number is required"
    }
  ]
}

Conflicting Date Range Queries

In cases where multiple date filter types are provided, an error will be provided. For example this includes adding both SubmittedStart and SubmittedMinAgo filters or SubmittedStart and ProcessedStart.

{
  "data": [
    {
      "ErrorMsg": "Please use SubmittedStart OR SubmittedMinAgo"
    }
  ]
}

Pagination and Cache Validation

If NoCache and UseCache query parameters are used simultaneously:

{
  "data": [
    {
      "ErrorMsg": "NoCache and UseCache cannot be combined"
    }
  ]
}

If UseCache is used but Cache table is not set (using setCache):

{
  "data": [
    {
      "ErrorMsg": "Please set your Cache table using the API Call setCache and try again"
    }
  ]
}