diff --git a/.vscode/settings.json b/.vscode/settings.json index 746e8ba..a28f075 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -4,6 +4,7 @@ "cSpell.words": [ "configparser", "DDTHH", + "isnull", "markdoc", "Onpsring", "prismjs" diff --git a/src/app/components/CodeSnippet.module.css b/src/app/components/CodeSnippet.module.css index 0c8b0f6..257ba6e 100644 --- a/src/app/components/CodeSnippet.module.css +++ b/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; diff --git a/src/app/components/SideBar.module.css b/src/app/components/SideBar.module.css index 79558f2..dbb2e3d 100644 --- a/src/app/components/SideBar.module.css +++ b/src/app/components/SideBar.module.css @@ -6,6 +6,10 @@ padding: 1rem; } +.link { + text-decoration: none; +} + .title { font-size: 1rem; white-space: nowrap; diff --git a/src/app/components/SideBar.tsx b/src/app/components/SideBar.tsx index 8cd01d5..b58c5f3 100644 --- a/src/app/components/SideBar.tsx +++ b/src/app/components/SideBar.tsx @@ -91,7 +91,7 @@ export default function SideBar({ }) { return (
- +

Onspring{' '} API diff --git a/src/docs/version_002/docsStructure.ts b/src/docs/version_002/docsStructure.ts index 47640ba..99582b5 100644 --- a/src/docs/version_002/docsStructure.ts +++ b/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', + }, ], }, ], diff --git a/src/docs/version_002/resources/records/get_record_by_id/copy.md b/src/docs/version_002/resources/records/get_record_by_id/copy.md index e295b64..33eef50 100644 --- a/src/docs/version_002/resources/records/get_record_by_id/copy.md +++ b/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. --- diff --git a/src/docs/version_002/resources/records/get_record_by_id/example.md b/src/docs/version_002/resources/records/get_record_by_id/example.md index 40fd92c..067406a 100644 --- a/src/docs/version_002/resources/records/get_record_by_id/example.md +++ b/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' \ diff --git a/src/docs/version_002/resources/records/get_records_by_app/copy.md b/src/docs/version_002/resources/records/get_records_by_app/copy.md index 5d87d56..7b91fc8 100644 --- a/src/docs/version_002/resources/records/get_records_by_app/copy.md +++ b/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 %} diff --git a/src/docs/version_002/resources/records/get_records_by_app/example.md b/src/docs/version_002/resources/records/get_records_by_app/example.md index b9bdc77..b11bd4d 100644 --- a/src/docs/version_002/resources/records/get_records_by_app/example.md +++ b/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' \ diff --git a/src/docs/version_002/resources/records/get_records_by_ids/copy.md b/src/docs/version_002/resources/records/get_records_by_ids/copy.md index 59b789a..1689ee8 100644 --- a/src/docs/version_002/resources/records/get_records_by_ids/copy.md +++ b/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. --- diff --git a/src/docs/version_002/resources/records/get_records_by_query/copy.md b/src/docs/version_002/resources/records/get_records_by_query/copy.md new file mode 100644 index 0000000..6a8c4c8 --- /dev/null +++ b/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. diff --git a/src/docs/version_002/resources/records/get_records_by_query/example.md b/src/docs/version_002/resources/records/get_records_by_query/example.md new file mode 100644 index 0000000..8ced4e6 --- /dev/null +++ b/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{ 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 %}