REST WebAPI search
SuperOffice REST APIs expose search endpoints that API consumers use to submit search queries.
Examples of these endpoints are:
/api/v1/Appointment/api/v1/Contact/api/v1/Person
There is also the general Archive endpoint:
/api/v1/Archive/SimpleSale/api/v1/Archive/FindSale/api/v1/Archive/LastTickets
Each endpoint, accessed by a GET request without parameters, is expected to be an OData URI query.
OData is a standard for specifying queries and getting results back. OData is a way to access the archive providers in NetServer.
OData
The OData URIs are expected in a structured query format, which is then server-side transformed into data structures understood by archive providers.
/api/v1/contact?$select=field1,field2&$filter=contactId eq 5
/-root-/-resource-/-query options --------------------------/
An OData URI accepts any number of the following options that are used to formulate logical database queries.
| Options | Type | Description |
|---|---|---|
| $select | string | Comma-separated list of column names to return. "nameDepartment,fullname,category". Can also use aggregation functions and modifiers: "Count(category):Footer" |
| $filter | string | Expression to restrict the results. e.g.: "name begins 'foo' and category gt 1" |
| $orderBy | string | Comma separated list of column names to sort by, with optional direction. "name asc,fullname,category desc" |
| $entities | string | Comma separated list of entity names to use. Default = "". "contact, person" |
| $top | int32 | Number of rows to return in results |
| $skip | int32 | Number of rows from database to skip before returning results |
| $mode | Enum: Slim, Full | FULL (with raw values and hints for each value) or SLIM (just the display values) |
| $options | string | Provider specific options. e.g: "GrandTotal=true" |
| $context | string | Provider specific context parameter. |
| $format | string | Set XML or JSON output format; override the format determined from Accept header. |
| $jsonSafe | bool | Make output names into JSON safe property names. Replace all unsafe characters with _ underscore. |
| $output | Enum: Logical, Display | Return Logical or Display values in SLIM mode. Logical returns true/false for booleans, Display returns icon hints. Dates are always returned as ISO strings. |
The OData - Archive Provider connection
Because every OData query performs a search using an archive provider, it's important to understand the relationship between the OData query options and how that structure gets transformed into something the underlying archive provider can understand.
OData queries provide the means to submit a query with SELECT columns, WHERE criteria, ORDER BY instructions, and paging information.
Looking at the Sale endpoint, select the GET Sale node. In addition to providing clues for how to construct an OData query, these pages all detail which archive provider is used by the endpoint to perform the query.
The name of the archive provider is located just above the Filter section. Locate the paragraph that begins with Calls the Archive service using the "{ArchiveProvider}" archive." The name of the archive provider matches one that is listed in the Archive Provider pages.
The GET Sale endpoint uses the FindSale archive provider.
214, 157, 133
$select columns
All available columns, shown under the blue rectangle, are listed under the Supported Columns text on the FindSale archive provider page.
Archive provider pages also list the column data types and whether or not the column can be used in an ORDER BY statement.
$filter operators
Difference data types can have different operators. Each OData search page contains a table of data types and their associated operators.
| Data type | Description |
|---|---|
| Bool | set |
| Int, Decimal | eq, ne, lt, gt, set, equals, greater, less, unequals, between |
| String | begins, between, contains, is, notBegins, notContains, isNot |
| Date | before, date, after, between, dateBetween |
| DateTime | dateTime, beforeTime, afterTime |
| Unary (Days) | beforeToday, today, afterToday |
| Unary (Weeks) | lastWeek, thisWeek, nextWeek |
| Unary (Months) | lastMonth, thisMonth, nextMonth |
| Unary (Quarter) | lastQuarter, thisQuarter, nextQuarter |
| Unary (Year) | thisHalf, thisYear |
| Associate | associateIsOneOf, associateIsNotOneOf, currentAssociate |
| Lists | equals, oneOf, notOneOf |
Read more about using filters and the dynamic dot-syntax provider.
You can fetch metadata - information about archives to do "reflection" on the available archives.
Example searches
- Associate
- Boolean
- Contact (company)
- Date
- DateTime
- Lists
- Numbers (integer, decimal, float)
- Strings
- Unary (day, week, month, quarter, year)