Common GET parameters

Many HTTP query parameters in BEdita 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 retrieve

page_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 response

page is the current page number

page_count is the total number of pages

page_items is the numer of items displayed in this page (maximum is page_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 or filter[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 value

filter[{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 first name

/objects?filter[id][gt]=100 return users with id 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]=.. or q=.. 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 given center point expressed in terms of latitude and longitude; each item will show in meta.extra.distance the distance in meters to the center 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 after 2017-08-01

/events?filter[date_ranges][end_date][le]=2017-08-15 events with end date lesser than or equal to 2017-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 between 2017-07-01 and 2017-07-30