OData (Open Data protocol) is an open protocol that allows the creation and consumption of queryable and interoperable RESTful APIs in a simple and standard way.
In short, it gives you the possibility to filter the data directly in the request URL.
Wello API is using version 4 of OData.
The goal is not to fully describe it here, but if you need more information (like $filters examples) you will find it on the website of OData http://www.odata.org/documentation/.
Before all, be aware that OData has a paging mechanism. It means that when you request a list of objects (a HTTP GET), it’s possible that you will not retrieve the full list, but only the first page. See chapter "Paging" for more information.
IMPORTANT! OData paging is only supported using JSON content-type, it is not supported using XML content-type. If you use XML, you can use the "$top" functionality followed by the "$skip" functionality as described below. See "Paging" for more information
Take care, ODATA is case sensitive. It means +AND+ on the $filters will not work but well +and+.
OData has some conventions about the URL. Here are the major conventions,
Getting a list of data
E.g. Retrieving a list of Companies
HTTP GET : https://developers.wello.solutions/api/Company
Getting a single entity using its id
E.g. Retrieving a Company that has an id of "224566b0-f5d7-406b-ad60-56295d86a95b"
HTTP GET : https://developers.wello.solutions/api/Company(224566b0-f5d7-406b-ad60-56295d86a95b)
Filtering of data $filter
OData filters allow users to retrieve lists of data based on certainconditions.
E.g.1 Getting only the list of companies that have been modified after 2nd of June 2015
HTTP GET : https://developers.wello.solutions/api/Company?$filter=modified_dateutc+gt+'2015-06-02T00:00:00.000Z'
E.g.2 Companies which have been modified after 2nd of June 2015 and of which name equals to ‘TEST API SA’
HTTP GET : https://developers.wello.solutions/api/Company?$filter=modified_dateutc+gt+'2015-06-02T00:00:00.000Z'+and+name+eq+'TEST+API+SA'
E.g.3 Use of multiple conditions together
HTTP GET : https://developers.wello.solutions/api/Company?$filter=modified_dateutc+gt+'2015-06-02T00:00:00.000Z'+and+name+eq+'TEST+APIL+SA'+and+company_type_id+eq+ab092950-6a75-4837-b093-bb3a8cefb26b
E.g.4 Use of a Guid as a filter
HTTP GET : https://developers.wello.solutions/api/Company?$filter=company_type_id+eq+ab092950-6a75-4837-b093-bb3a8cefb26b
Ordering of data $orderby
E.g. Retrieving a sorted list of companies that is filtered on a specific type
HTTP GET : https://developers.wello.solutions/api/Company?$filter=company_type_id+eq+ED7D575C-796B-4019-9A87-D145EA8A6B1E&$orderby=name+desc
Limit the number of data $top
The "$top" functionality requests a number of items in the queried collection to be included in the result.
E.g. Retrieve only the first 10 companies in the table Company.
HTTP GET : https://developers.wello.solutions/api/Company?$top=10
Exclude data $skip
The "$skip" functionality is used to skip a number of items that should not be included in the result.
E.g. Retrieve Companies starting with the 9th Company in the table Company
HTTP GET : https://developers.wello.solutions/api/Company?$skip=8
Selecting specific data $select
This option allows users to select columns of the table should be returned.
E.g. Retrieve only the name, street, street_number and phone data of all the Companies.
$select is NOT working with XML format, but only with JSON. (Known issue with Odata)
HTTP GET : https://developers.wello.solutions/api/Company?$select=name,street,street_number,phone