docs: add section for get records by query

.vscode/settings.json

@@ -4,6 +4,7 @@
   "cSpell.words": [
     "configparser",
     "DDTHH",
+    "isnull",
     "markdoc",
     "Onpsring",
     "prismjs"

src/app/components/CodeSnippet.module.css

@@ -34,6 +34,10 @@
   border-radius: 10px;
 }
 
+.snippetContent>pre::-webkit-scrollbar-corner {
+  background-color: transparent;
+}
+
 @-moz-document url-prefix() {
   .snippetContent>pre {
     margin-right: 1rem;

src/app/components/SideBar.module.css

@@ -6,6 +6,10 @@
   padding: 1rem;
 }
 
+.link {
+  text-decoration: none;
+}
+
 .title {
   font-size: 1rem;
   white-space: nowrap;

src/app/components/SideBar.tsx

@@ -91,7 +91,7 @@ export default function SideBar({
 }) {
   return (
     <div className={styles.container}>
-      <Link href="/">
+      <Link href="/" className={styles.link}>
         <h1 className={styles.title}>
           <span className={styles.onspring}>Onspring</span>{' '}
           <span className={styles.api}>API</span>

src/docs/version_002/docsStructure.ts

@@ -68,6 +68,12 @@ export const versionTwo: DocsStructure = {
               copy: 'copy.md',
               example: 'example.md',
             },
+            {
+              title: 'Get Records by Query',
+              folder: 'get_records_by_query',
+              copy: 'copy.md',
+              example: 'example.md',
+            },
           ],
         },
       ],

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

@@ -14,7 +14,7 @@ This endpoint returns a single [record](#records) based on the given record id.
 
 - appId
 - `number`
-- The id of the app or survey that the record belongs to.
+- The id of the app or survey that contains the record.
 
 ---
 

src/docs/version_002/resources/records/get_record_by_id/example.md

@@ -1,6 +1,6 @@
 # Retrieving a record from an app
 
-{% code method="GET" heading="/Records/appId/{appID}/recordId/{recordID}" defaultLanguage="bash" %}
+{% code method="GET" heading="/Records/appId/{appId}/recordId/{recordId}" defaultLanguage="bash" %}
 
 ```bash
 curl --location 'https://api.onspring.com/Records/appId/195/recordId/1' \

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

@@ -14,7 +14,7 @@ This endpoint returns a [paged](#pagination) collection of [records](#records) f
 
 - appId
 - `number`
-- The id of the app or survey.
+- The id of the app or survey that contains the records.
 
 {% /table %}
 

src/docs/version_002/resources/records/get_records_by_app/example.md

@@ -1,6 +1,6 @@
 # Retrieving records for an app
 
-{% code method="GET" heading="/Records/appId/{appID}" defaultLanguage="bash" %}
+{% code method="GET" heading="/Records/appId/{appId}" defaultLanguage="bash" %}
 
 ```bash
 curl --location 'https://api.onspring.com/Records/appId/195' \

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

@@ -14,7 +14,7 @@ This endpoint returns a batch of [records](#records) that match the given ids.
 
 - appId
 - `number`
-- The id of the app that contains the records.
+- The id of the app or survey that contains the records.
 
 ---
 

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

@@ -0,0 +1,105 @@
+# Get Records by Query {% #get-records-by-query %}
+
+This endpoint returns a [paged](#pagination) collection of [records](#records) for a given app or survey.
+
+## Query Parameters
+
+**Note:** [Pagination](#pagination) query parameters can be used to control the number of records returned.
+
+## Request Body Properties
+
+{% table %}
+
+- Property Name
+- Data Type
+- Description
+
+---
+
+- appId
+- `number`
+- The id of the app or survey that contains the records.
+
+---
+
+- filter
+- `string`
+- A [filter](#filter) expression that will be used to filter the records returned.
+
+---
+
+- fieldIds
+- `number[]`
+- The ids of the fields to return in the records.
+
+---
+
+- dataFormat
+- `string`
+- The [format](#data-format) of the field data in the response. Valid values are `raw` and `formatted`. If not specified, `raw` will be used.
+
+{% /table %}
+
+## Filter {% #filter %}
+
+A filter expression is a string that is used to filter records returned by the [Get Records by Query](#get-records-by-query) endpoint. The filter operators available, the fields they are applicable to, and the syntax for each operator are described below.
+
+{% table %}
+
+- Operator
+- Description
+- Applicable Fields
+
+---
+
+- `eq`
+- Determines if the field equals a value.
+- `Text`, `number`, `date`, and `auto-number` fields and formula fields that have an output type of `text`, `number`, or `date`.
+
+---
+
+- `ne`
+- Determines if the field does not equal a value.
+- `Text`, `number`, `date`, and `auto-number` fields and formula fields that have an output type of `text`, `number`, or `date`.
+
+---
+
+- `contains`
+- Determines if the field contains a list value. List value can be its id or name.
+- `List` fields and formulas with output type of `list`.
+
+---
+
+- `isnull`
+- Determines if the field is null.
+- `Text`, `number`, `date`, and `auto-number` fields and formula fields that have an output type of `text`, `number`, or `date`.
+
+---
+
+- `notnull`
+- Determines if the field is not null.
+- `Text`, `number`, `date`, and `auto-number` fields and formula fields that have an output type of `text`, `number`, or `date`.
+
+---
+
+- `lt`
+- Determines if the field is less than a value.
+- `Number`, `date`, and `auto-number` fields and formula fields that have an output type of `number` or `date`.
+
+---
+
+- `gt`
+- Determines if the field is greater than a value.
+- `Number`, `date`, and `auto-number` fields and formula fields that have an output type of `number` or `date`.
+
+---
+
+{% /table %}
+
+### Delimiters
+
+When using a string value in a filter expression you must use single quotes (`'`) to delimit the string value. When using a date value in a filter expression you must use single quotes (`'`) to delimit the date value and the delimited value should be preceded by the word `datetime`.
+
+### Combining Filters
+
+You can combine multiple filters using the `and` and `or` operators as well as parentheses to control the order of operations. The `not` operator can be used to negate a filter.

src/docs/version_002/resources/records/get_records_by_query/example.md

@@ -0,0 +1,176 @@
+# Querying for records in an app
+
+{% code method="POST" heading="/Records/Query" defaultLanguage="bash" %}
+
+```bash
+curl --location 'https://api.onspring.com/Records/Query' \
+--header 'X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000' \
+--header 'x-api-version: 2' \
+--header 'Content-Type: application/json' \
+--data '{
+    "AppId": 195,
+    "Filter": "6983 eq '\''Test Task 5'\''",
+    "FieldIds": [6983,6986,6987,6985,6984],
+    "DataFormat": "Formatted"
+}'
+```
+
+```csharp
+using Onspring.API.SDK;
+using Onspring.API.SDK.Models;
+using Onspring.API.SDK.Enums;
+
+var onspringClient = new OnspringClient(
+  config.BaseUrl,
+  config.ApiKey
+);
+
+var queryRequest = new QueryRecordsRequest
+{
+  AppId = 195,
+  Filter = "not (6987 lt 10 or 6986 eq 'In Progress') and 6985 gt datetime'2014-03-01T00:00:00.0000000'",
+  FieldIds = new List<int>{ 6983, 6986, 6987, 6985, 6984 },
+  DataFormat = DataFormat.Formatted,
+};
+
+var queryResponse = await onspringClient.QueryRecordsAsync(queryRequest);
+var records = queryResponse.Value.Items;
+
+foreach (ResultRecord record in records)
+{
+  Console.WriteLine($"AppId: {record.AppId}, RecordId: {record.RecordId}");
+
+  foreach (RecordFieldValue fieldValue in record.FieldData)
+  {
+      Console.WriteLine($"FieldId: {fieldValue.FieldId}, Type: {fieldValue.Type}");
+  }
+}
+```
+
+```javascript
+import {
+  DataFormat,
+  FilterOperators,
+  OnspringClient,
+  QueryFilter,
+  QueryRecordsRequest,
+} from 'onspring-api-sdk';
+import dotenv from 'dotenv';
+dotenv.config();
+
+const client = new OnspringClient(
+  process.env.BASE_URL,
+  process.env.API_KEY
+);
+
+const filter = new QueryFilter(
+  6987,
+  FilterOperators.GreaterThan,
+  0
+);
+
+const request = new QueryRecordsRequest(
+  195,
+  filter,
+  [6983, 6986, 6987, 6985, 6984],
+  DataFormat.Formatted
+);
+
+const res = await client.queryRecords(request);
+const records = res.data.items;
+
+for (const record of records) {
+  console.log(record);
+}
+```
+
+```python
+from OnspringApiSdk.OnspringClient import OnspringClient
+from OnspringApiSdk.Models import QueryRecordsRequest
+from OnspringApiSdk.Enums import DataFormat
+from configparser import ConfigParser
+
+cfg = ConfigParser()
+cfg.read('config.ini')
+
+key = cfg['prod']['key']
+url = cfg['prod']['url']
+
+client = OnspringClient(url, key)
+
+fieldId = 6983
+operator = 'eq'
+value = '\'Test Task 5\''
+
+request = QueryRecordsRequest(
+  appId=195,
+  filter=f'{fieldId} {operator} {value}',
+  fieldIds=[9686],
+  dataFormat=DataFormat.Formatted.name,
+)
+
+response = client.QueryRecords(request)
+
+print(f'Status Code: {response.statusCode}')
+print(f'Page Size: {response.data.pageSize}')
+print(f'Page Number: {response.data.pageNumber}')
+print(f'Total Pages: {response.data.totalPages}')
+print(f'Total Records: {response.data.totalRecords}')
+
+for record in response.data.records:
+  print(f'AppId: {record.appId}')
+  print(f'RecordId: {record.recordId}')
+
+  for field in record.fields:
+    print(f'Type: {field.type}')
+    print(f'FieldId: {field.fieldId}')
+    print(f'Value: {field.GetResultValueString()}')
+```
+
+{% /code %}
+
+{% code heading="RESPONSE" defaultLanguage="json" %}
+
+```json
+{
+  "pageNumber": 1,
+  "pageSize": 1,
+  "totalPages": 1,
+  "totalRecords": 1,
+  "items": [
+    {
+      "appId": 195,
+      "recordId": 5,
+      "fieldData": [
+        {
+          "type": "String",
+          "fieldId": 6983,
+          "value": "Test Task 5"
+        },
+        {
+          "type": "String",
+          "fieldId": 6986,
+          "value": "Complete"
+        },
+        {
+          "type": "Integer",
+          "fieldId": 6987,
+          "value": 2
+        },
+        {
+          "type": "String",
+          "fieldId": 6985,
+          "value": "12/31/2021 6:00 AM"
+        },
+        {
+          "type": "String",
+          "fieldId": 6984,
+          "value": "This is a test!"
+        }
+      ]
+    }
+  ]
+}
+```
+
+{% /code %}