1. WMS REST API Guide
  2. Input Data Types

Input Data Types

Lgfapi supports user input depending on the HTTP method:

  • GET/HEAD
    • Query string parameters
  • POST
    • Request body data
      • The format must be JSON or XML
    • The “format” query sting parameter alone is supported to specify the desired format for the response.

Although the input formats may be type ambiguous, the input value is cast to the appropriate type as defined in the entity’s field metadata. Some fields have naming conventions that are outlined below. The following types are supported for user input:

String/Text

Query String: …/?field=abc123

JSON: {“field”: “abc123”}

XML: <field>abc1234</field>

Integer

Query String: …/?field=123

JSON: {“field”: 123}

XML: <field>123</field>

Numeric/Decimal

Query String: …/?field=1.234

JSON: {“field”: "1.234"}

XML: <field>1.234</field>
Note: Special Note about Numeric/Decimal Values: When sending decimal values in a JSON request, it is recommended to send them wrapped in double quotes like a string value, as seen in the example above. This will prevent against any loss of precision as part of the lgfapi request.

Boolean

Except for a few specific cases, all True/False Boolean field names end with “_flg”.

The input value for all formats should be either “true” or “false”.

Query String: …/?field_flg=true

JSON: {“field_flg”: true}

XML: <field_flg>true</field_flg>

Temporal (Date/Time)

All date, time, and date-time fields require the iso-8601 format: YYYY-mm-ddTHH:MM:SS.ffffff

Note that the microsecond component “f” is optional. Using January 30th, 2018 at 6:30pm as an example:

Date

Field names for date-only fields typically end with “_date”.

Query String: …/?field_date=2018-01-30

JSON: {“field_date”: “2018-01-30”}

XML: <field_date>2018-01-30</field_date>

Time

Field names for time-only fields typically end with “_time”.

Query String: …/?field_time=18:30:00

JSON: {“field_time”: “18:30:00”}

XML: <field_time>18:30:00</field_time>

Date-time

Field names for date-time fields typically end with “_ts”.

All Date-time objects are assumed to be in the time zone of the user’s facility context. In other words, it should be the date/time you would expect to see if viewed by the user in the UI.

Query String: …/?field_ts=2018-01-30T18:30:00

JSON: {“field_ts”: “2018-01-3030T18:30:00”}}

XML: <field_ts>2018-01-3030T18:30:00</field_ts>

Date/Time Values and Time Zones

It is a recommended best practice to always pass time zone aware date-time values that include the time zone offset component so that there is no ambiguity. The following examples show the time zone specified as Indian Standard Time - IST (+05:30):

  • Query String:field_ts=2024-08-07T00:00:00+05:30
  • JSON: {“field_ts”:“2024-08-07T00:00:00+05:30”}
  • XML:<field_ts>2024-08-07T00:00:00+05:30</field_ts>

This data-time indicates 12:00 am on August 7th in India. The date is converted and stored in WMS appropriately using the offset provided on the field. When this date time is pulled up in a WMS UI screen, it would be displayed as per the time zone of the default facility of the user. For example, in an IST facility (Tz +05:30), the user would see this as 12:00 am of August 7th. In a Singapore facility (Tz +08:00), the user would see this as 2:30 am on August 7th.

  • Query String: field_ts=2018-01-30T18:30:00
  • JSON: {“field_ts”: “2018-01-3030T18:30:00”}
  • XML: <field_ts>2018-01-3030T18:30:00</field_ts>

Additional Note about Timezone

If sending a time zone component, ensure that the API user's default facility time zone is same as the time zone of the facility in the payload, else the conversion may result in undesirable results

Example 1:

o API user's default facility time zone: +05:30

o Time zone of the facility passed in the payload: +05:30

o Timestamp sent with any time zone is converted appropriately.

Example 2:

o API user’s default facility time zone: +08:00

o Time zone of the facility passed in the payload: +05:30

o Timestamp sent with any time zone is NOT converted appropriately.

If you are managing facilities in multiple time zones, ensure that you create as many API users as the number of time zones. Each user needs to have a default facility that represents a different time zone and used for posting API requests for the facilities in the respective time zones to avoid undesirable results as described in Example 2.

The other option is to use time zone naïve data-time value as described below.

If a time zone naive date-time value is received by lgfapi, it is assumed to be in the time zone of the API user’s default facility. In other words, it would be the date/time you expect to see if viewed by the user in the UI for their default facility. These are date-time values that DO NOT include the time zone offset component as illustrated in the following example.

  • Query String:field_ts=2024-08-07T00:00:00
  • JSON: {“field_ts”:“2024-08-07T00:00:00”}
  • XML:<field_ts>2024-08-07T00:00:00</field_ts>

In this example, if the API user's default facility is Atlanta (Tz -04:00 EDT), the date-time value indicates 12:00 am on August 7th in Atlanta. The date is converted and stored in WMS appropriately using the time zone of the API user’s default facility. When this date time is pulled up in a WMS UI screen, it would be displayed as per the time zone of the default facility of the user. For example, in an ATL facility (Tz -04:00 EDT), the user would see this as 12:00 am of August 7th. In a Singapore facility (Tz +08:00), the user would see this as 12:00 pm on August 7th.

Relational

Relational fields are when one resource has a link to another resource. These fields always end in “_id” and by default, are integer values. They are unique when filtering, in that you can use the double-underscore (“__”) notation to reference a related resource’s fields, or even nested related resources. This is covered in more detail in the Resource Result Set Filtering section.

Query String: …/?field_id=1

JSON: {“field_id”: 1}

XML: <field_id>1</field_id>