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>

Special Note about JSON 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

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

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 UTC (+00:00):

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

However, if a time zone naive date-time value is received by lgfapi, it is assumed to be in the time zone of the 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.

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

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>