docs: add information on data format

.markdownlint.json

@@ -19,7 +19,7 @@
   "MD022": true,
   "MD023": true,
   "MD024": true,
-  "MD025": true,
+  "MD025": false,
   "MD026": true,
   "MD027": true,
   "MD028": true,

src/docs/version_002/data_format/copy.md

@@ -0,0 +1,107 @@
+# Data Format {% #data-format %}
+
+When retrieving data via the Onspring API using certain endpoints you can specify the format of the data being retrieved. The format can be will be specified either in a query parameter or in the request body. These endpoints are:
+
+- [Get Records by App](#get-records-by-app)
+- [Get Record by Id](#get-record-by-id)
+- [Get Records by Ids](#get-records-by-ids)
+- [Get Records by Query](#get-records-by-query)
+- [Get Report by Id](#get-report-by-id)
+
+The format values can be either `Raw` or `Formatted`. If the format is not specified then the default format is `Raw`. The format specified will be applied to all the data being retrieved. The impact of the format on the data retrieve will depend on the type of field. The following tables shows the impact of the format on the data retrieved for each field type.
+
+## Raw Format {% #raw-format %}
+
+{% table .propertiesTable %}
+
+- Field Type
+- Return Data Type
+- Description
+
+---
+
+- AutoNumber
+- `number`
+- The field value will be returned as a number.
+
+---
+
+- Date/Time
+- `string`
+- The field value will be returned as a string in the format `YYYY-MM-DDTHH:MM:SSZ`.
+
+---
+
+- List
+- `string` or `string[]`
+- The field value will be returned as a string or an array of strings where the strings are the GUID ids of the selected list items.
+
+---
+
+- Number
+- `number`
+- The field value will be returned as a number.
+
+---
+
+- Text
+- `string`
+- The field value will be returned as a string including any HTML markup.
+
+---
+
+- Time Span
+- `object`
+- The field value will be returned as a [Time Span](#time-span-field-value) object.
+
+---
+
+{% /table %}
+
+## Formatted Format {% #formatted-format %}
+
+{% table .propertiesTable %}
+
+- Field Type
+- Return Data Type
+- Description
+
+---
+
+- AutoNumber
+- `string`
+- The field value will be returned as a string including any configured formatting.
+
+---
+
+- Date/Time
+- `string`
+- The field value will be returned as a string including any configured formatting.
+
+---
+
+- List
+- `string` or `string[]`
+- The field value will be returned as a string or an array of strings where the strings are the names of the selected list items.
+
+---
+
+- Number
+- `string`
+- The field value will be returned as a string including any configured formatting.
+
+---
+
+- Text
+- `string`
+- The field value will be returned as a string without any HTML markup.
+
+---
+
+- Time Span
+- `string`
+- The field value will be returned as a string which represents the time span entered.
+
+---
+
+{% /table %}

src/docs/version_002/data_format/example.md

@@ -0,0 +1,107 @@
+# The Values in a Raw Response
+
+{% code Heading="RAW" defaultLanguage="json" %}
+
+```json
+{
+  "appId": 130,
+  "recordId": 1,
+  "fieldData": [
+    {
+      "type": "Integer",
+      "fieldId": 4745, // AutoNumber Field
+      "value": 1
+    },
+    {
+      "type": "Date",
+      "fieldId": 4800, // Date/Time Field
+      "value": "2023-02-15T06:00:00Z"
+    },
+    {
+      "type": "Guid",
+      "fieldId": 4833, // Single Select List Field
+      "value": "9a08da5e-db5d-447f-9be9-ce8d7d7e61a7"
+    },
+    {
+      "type": "GuidList",
+      "fieldId": 4830, // Multi Select List Field
+      "value": [
+        "624714d7-d22d-414f-ab62-9071d993e796",
+        "46f87c6b-be0a-46a2-b7de-e100779e1643"
+      ]
+    },
+    {
+      "type": "Decimal",
+      "fieldId": 4803, // Number Field
+      "value": 100
+    },
+    {
+      "type": "String",
+      "fieldId": 4805, // Text Field
+      "value": "<p>This is a test</p>"
+    },
+    {
+      "type": "TimeSpan",
+      "fieldId": 4810,
+      "value": {
+        "quantity": 11,
+        "increment": "Seconds",
+        "recurrence": "EndAfterOccurrences",
+        "endAfterOccurrences": 1
+      }
+    }
+  ]
+}
+```
+
+{% /code %}
+
+# The Values in a Formatted Response
+
+{% code Heading="RAW" defaultLanguage="json" %}
+
+```json
+{
+  "appId": 130,
+  "recordId": 1,
+  "fieldData": [
+    {
+      "type": "String",
+      "fieldId": 4745, // AutoNumber Field
+      "value": "recordId-1"
+    },
+    {
+      "type": "String",
+      "fieldId": 4800, // Date/Time Field
+      "value": "Wednesday, February 15, 2023 6:00 AM"
+    },
+    {
+      "type": "String",
+      "fieldId": 4833, // Single Select List Field
+      "value": "list_value_1"
+    },
+    {
+      "type": "StringList",
+      "fieldId": 4830, // Multi Select List Field
+      "value": ["list_value_1", "list_value_2"]
+    },
+    {
+      "type": "String",
+      "fieldId": 4803, // Number Field
+      "value": "$100 dollars"
+    },
+    {
+      "type": "String",
+      "fieldId": 4805, // Text Field
+      "value": "This is a test"
+    },
+    {
+      "type": "String",
+      "fieldId": 4810, // TimeSpan Field
+      "value": "Every 11 Second(s) End After 1 Occurrences"
+    }
+  ]
+}
+```
+
+{% /code %}

src/docs/version_002/docsStructure.ts

@@ -18,6 +18,13 @@ export const versionTwo: DocsStructure = {
       example: 'example.md',
       children: [],
     },
+    {
+      title: 'Data Format',
+      folder: 'data_format',
+      copy: 'copy.md',
+      example: 'example.md',
+      children: [],
+    },
     {
       title: 'Pagination',
       folder: 'pagination',

src/docs/version_002/pagination/copy.md

@@ -14,16 +14,19 @@ When making a request to one of the endpoints that support pagination you can us
 {% table .propertiesTable %}
 
 - Parameter Name
+- Data Type
 - Description
 
 ---
 
 - PageNumber
+- `number`
 - The page number to retrieve. The default value is `1`.
 
 ---
 
 - PageSize
+- `number`
 - The number of objects to retrieve per page. The default value is `50`. The maximum value is `1000`.
 
 {% /table %}

src/docs/version_002/pagination/example.md

@@ -8,7 +8,11 @@
   "pageSize": 1,
   "totalPages": 1,
   "totalRecords": 1,
-  "items": []
+  "items": [
+    {
+      ...,
+    }
+  ]
 }
 ```
 

src/docs/version_002/resources/records/field_values/copy.md

@@ -142,13 +142,13 @@ These are objects representing a field value in a record. They will comprise the
 
 - endByDate
 - `string`
-- The end date of the time span. Used if `recurrence` is set to `EndByDate`.
+- The end date of the time span. This will only be returned if `recurrence` is set to `EndByDate`.
 
 ---
 
 - endAfterOccurrences
 - `number`
-- The number of occurrences of the time span. Used if `recurrence` is set to `EndAfterOccurrences`.
+- The number of occurrences of the time span. This will only be returned if `recurrence` is set to `EndAfterOccurrences`.
 
 {% /table %}
 
@@ -184,6 +184,12 @@ These are objects representing a field value in a record. They will comprise the
 - `string`
 - The storage location of the file. Can be one of the following values: `Internal`, `OneDrive`, `GoogleDrive`.
 
+---
+
+- downloadLink
+- `string`
+- The download link for the file. This will only be returned if the `storageLocation` is not `Internal`.
+
 {% /table %}
 
 ### Scoring Group Field Value {% #scoring-group-field-value %}