Common GET parameters¶
Many HTTP query parameters in BEdita4 API GET method calls are common and may be used to manipulate API response and get only the data you need in your application.
Common parameters described here may be used in all API endpoints that handle entities/objects directly.
They are available in all endpoints except few special ones like: /auth
, /home
, /signup
and /status
. These endpoints are designed to handle particular use cases where lists of resources or objects are not directly handled.
Pagination¶
page
- select page number to retrievepage_size
- define page size; default page size and maximum possible size are defined via configuration parameter (defaults are 20 and 100) see Pagination
Examples:
/objects?page=2
- get page number 2/objects?page_size=42
- impose 42 as page size in response/objects?page_size=42&page=3
- get page number 3 using 42 as page size
In every GET response containing lists pagination data is available in a special section under meta / pagination
Example response:
Suppose we have 125 items available for our request, using 20 as
page_size
, selecting page number 7 we get{ "links": { ... }, "data": { ... }, "meta": { "pagination": { "count": 125, "page": 7, "page_count": 7, "page_items": 5, "page_size": 20 } } }
Where, as you may easily guess:
count
is the total number of items in responsepage
is the current page numberpage_count
is the total number of pagespage_items
is the numer of items displayed in this page (maximum ispage_size
)page_size
is the page size, max number of items for each page
Field selection¶
fields
- decide which fields are displayed in a response, comma separeted list
Search¶
q
orfilter[query]
- perform a natural language search using a filter, see Search Query filter below
Sort¶
sort
- sort items using a field in ascending or descending order, descending order is obtained prepending minus-
to field name
Examples:
/users?sort=username
return users alphabetically by username/users?sort=-username
return users alphabetically from last to first by username (reverse order)/roles?sort=-id
roles from last to first id
Filters¶
Filters are one the most powerful and versatile tools in BEdita API in order to retrieve only resources or objects you really need in your application.
Filter expressions¶
Generally every filter in a query string will have following syntax:
filter[{item}]={value}
the simplest form, a filter item should be equal to some valuefilter[{item}][{op}]={value}
is a logical operation on filter value, where{op}
can have following values:
neq
,ne
,'!=
or<>
negation operator, meaning that filter item shoud not be equal to{{value}}
lt
or<
less than operator, meaning that filter item shoud be less than{{value}}
lte
,le
or<=
less than or equal operator; filter item shoud be less than or equal to{{value}}
gt
or>
greater than operator; filter item shoud be greater than{{value}}
gte
,ge
or>=
greater than or equal operator; filter item should be greater than or equal to{{value}}
filter[{item}][]={value}
array sintax: add a value to an array representing possible values of a filter item
Filter expressions can be combined using &
separator as many times as you want, limited only by the URL size.
Too many filter
combinations may of course result in unwanted or meaningless results, use them with caution :)
Field filter¶
The simplest and most common filter: retrieve only resources that have a field equal to some value, or greater/less than some value.
Examples:
/users?filter[name]=Gustavo
get users that have Gustavo as firstname
/objects?filter[id][gt]=100
return users withid
greater than 100
Search Query filter¶
Simple text search may be performed with a query filter
/objects?filter[query]=gustavo
get objects that have gustavo in some of their textual fields/objects?q=gustavo
convience alias for the preceeding filter query -filter[query]=..
orq=..
are identical
Note: currently only raw text search is performed, more sophisticated actual natural language search will be available in a future release
Type filter¶
Type filters are used to select some object types, typically used in /objects
endpoint
/objects?filter[type]=events
select only objects of type events/objects?filter[type][ne]=documents
all object types except documents/objects?filter[type][]=locations&filter[type][]=profiles
select only locations and profiles
Geo filter¶
Geo filters are able to retrieve results on objects of type location
or on types extending locations
using geo coordinates.
/locations?filter[geo][center]=44.4944183,11.3464055
retrieve locations ordered by proximity to a givencenter
point expressed in terms of latitude and longitude; each item will show inmeta.extra.distance
the distance in meters to thecenter
point/locations?filter[geo][center]=44.4944183,11.3464055&filter[geo][radius]=5000
same as the above filter, but results are limited in a radius of 5km
Note: in order to work this filter requires that the underlying database supports geo-spatial functions like ST_GeomFromText
, this is true for MySQL 5.7 or PostGIS for instance.
Date ranges filter¶
Date ranges are entities used in some objects like events
to indicate start and end dates.
With this filter you are able to retrieve objects using conditions on date time intervals.
/events?filter[date_ranges][start_date][gt]=2017-08-01
events starting after2017-08-01
/events?filter[date_ranges][end_date][le]=2017-08-15
events with end date lesser than or equal to2017-08-15
/events?filter[date_ranges][start_date][gt]=2017-07-01&filter[date_ranges][end_date][lt]=2017-07-30
events starting and ending between2017-07-01
and2017-07-30