5.7 KiB
API request format
AyaNova uses a RESTful API and supports the JSON 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 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).
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