89 lines
5.7 KiB
Markdown
89 lines
5.7 KiB
Markdown
# API request format
|
|
|
|
AyaNova uses a RESTful API and supports the [JSON](https://www.json.org/) data interchange format exclusively.
|
|
No other data formats are supported, your code must supply and consume JSON formatted data.
|
|
|
|
All developer interaction with the AyaNova API is via the REST server interface only.
|
|
|
|
## API documentation
|
|
|
|
Your primary source of information on how to make API requests is the [API explorer console](api-console.md) where every route is documented and can be tested manually before coding.
|
|
|
|
## Date and time
|
|
|
|
All dates and times sent or retrieved from the REST interface must be in UTC / GMT time zone. It is the client's responsibility to display and accept dates in local format but interaction with the server is in UTC only.
|
|
|
|
## Localization
|
|
|
|
Every User account in AyaNova has their own UserOptions object which contains their personal localization settings such as time zone offset, currency symbol and numeric formatting options you can use this value to correctly display and interpret values at a client level.
|
|
|
|
In addition every user has their own locale setting ID which can be used to fetch and display text in the correct locale by using the methods in the Locale routes.
|
|
|
|
## Paging, sorting and filtering lists
|
|
|
|
Most list routes have a common method for paging sorting and filtering via query parameters provided to the route:
|
|
|
|
### Offset
|
|
|
|
This parameter controls the paging offset and is expected to be an integer. If no value is specified the default is 0.
|
|
|
|
### Limit
|
|
|
|
This parameter controls the number of items returned starting at the offset provided. The maximum allowed value is 1000, the default value is 25 if no value is specified.
|
|
|
|
### DataFilterId - Sorting and Filtering
|
|
|
|
Sorting and filtering are accomplished by providing an Id value in the DataFilterId parameter of a list for a pre-created and saved `DataFilter` object.
|
|
|
|
A DataFilter is created separately before it can be used with a list request via the DataFilter route (see the [API explorer console](api-console.md)).
|
|
|
|
A DataFilter object contains properties for filtering and sorting as well as a name as displayed for selection in the user interface and also properties that control who can select and use the filter (public or just a single User).
|
|
|
|
#### DataFilter.sort
|
|
|
|
This parameter controls the sort order of the data returned. It is expected to be a JSON array of objects that contain two fields a `fld` property that contains the string name of the field to be sorted by and a `dir` property that controls the direction of sorting and is one of two values "+" for Ascending or "-" for Descending. Multiple objects may be specified to sort by multiple columns in order from first to last specified in the array.
|
|
|
|
Note that this property of the DataFilter is expected to be a *string* representation of the JSON collection, not raw JSON.
|
|
|
|
For example the following Sort array will sort a list by Name first in ascending order and then by StartDate second in descending order:
|
|
|
|
```[{fld:"name", dir:"+"},{fld:"startdate", dir:"-"}```
|
|
|
|
To determine which field names are valid for a particular list you can make use of the `/FilterOptions` API route for that object which is available for any objects with sort and filterable lists.
|
|
|
|
If no sort parameter is provided the default is to sort by Id Descending so the most recently created objects appear first in the list.
|
|
|
|
#### DataFilter.filter
|
|
|
|
This parameter filters the data returned. It is expected to be a *string* representation of a JSON array of objects that contain three fields a `fld` property that contains the string name of the field to be sorted by, a `op` property that specifies what type of filter operation is required and optionally a `value` property when a comparison value is required such as a "Starts with" type of filter.
|
|
|
|
The `fld` property must be a valid field for the list in question. To determine which field names are valid for a particular list you can make use of the `/FilterOptions` API route for that object which is available for any objects with sort and filterable lists.
|
|
|
|
The `op` property must be a valid filter operation type. The 10 possible values for `op` are:
|
|
|
|
| OP | MEANING |
|
|
| ----- | ------------------------------ |
|
|
| = | Equality, `fld` data must equal `value` specified to be included in list |
|
|
| > | Greater than, `fld` data must be greater than `value` specified to be included in list |
|
|
| >= | Greater than or equality, `fld` data must be greater than or equal to `value` specified to be included in list |
|
|
| < | Less than, `fld` data must be less than `value` specified to be included in list |
|
|
| <= | Less than or equality, `fld` data must be less than or equal to `value` specified to be included in list |
|
|
| != | Not equal, `fld` data must not equal `value` specified to be included in list |
|
|
| %- | Starts with, `fld` data must start with `value` specified to be included in list |
|
|
| -% | Ends with, `fld` data must end with `value` specified to be included in list |
|
|
| -%- | Contains, `fld` data must contain `value` specified to be included in list |
|
|
| !-%- | Not contains, `fld` data must not contain `value` specified to be included in list |
|
|
|
|
|
|
Note that not all op values are valid for all data types, for example a date doesn't support a Contains type operator.
|
|
|
|
The `value` property
|
|
|
|
|
|
For example the following filter array JSON (in string format) will return only items where the Name starts with "Bob" and the Notes field exactly equals "Aardvark":
|
|
|
|
`"filter": "[ {\"fld\": \"name\", \"op\": \"%-\", \"value\": \"Bob\" }, { \"fld\": \"notes\", \"op\": \"=\", \"value\": \"Aardvark\" }]"
|
|
}`
|
|
|
|
If no filter parameter is provided no filtering will be done on the list
|