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.
- Request body data
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
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>