API Data Server (ADS) lets you retrieve data (JSON and CSV) and HTML from your database with 3rd party applications and/or websites (e.g. WordPress). This service can be used to fetch all sorts of data from your database. And HTML from your website, e.g. to embed a menu (based on a user’s state and permissions). This article does not describe all available functions, it explains the basics only. Contact us for further information.
Please note that ADS and the Infradox Partner API are two different things. For more information about the API used to set up live connections with other websites for searching and downloading, please read Infradox Partner API
Access Keys
ADS calls must include a unique key to make sure that your data can’t be accessed without the required permissions. If you need the key value, you can find it in Site configuration, Data access keys. You can not create a new key yourself, so create a ticket on xpertise.zendesk.com if you want to use this function. Access can be restricted to one (or several) IP addresses and you can specify permissions (what can be accessed) too.
Session data
Website Access
If you need to access state information – e.g. when integrating a WordPress or other website with the Infradox website – you can use the API to retrieve information about the current user’s session so that you can for instance display or hide menu items depending on whether the user is logged in or not.
Getting session information
Example URL:
http://www.web.com/api/www?key=21696-9E8E04-27B9E&cmd=sessiondata&si=97EC27B9E8E04BAF98E06216965396
Example result (JSON):
The JSON object has state information for the session id that you have specified. Infradox websites store the session id in the browser’s cookies. The cookies are read from page to page. The command (cmd) is sessiondata and the si parameter represents the user’s session id.
The attributes available in the JSON object will vary depending on whether the user is logged in or not, and the user’s permissions.
Getting a new session id
Example URL:
http://www.web.com/api/www?key=21696-9E8E04-27B9E&cmd=getsession
Example result:
{“session”:”97EC27B9E8E04BAF98E06216965396″,”guest”:1}
Getting HTML / page fragments
Example URL:
http://www.xsdevelop.com/api/www?cmd=html&t=templatename&key=21696-9E8E04-27B9E&si=97EC27B9E8E04BAF98E06216965396
To retrieve an HTML page or page fragment, use the t= parameter to specify the template to use. You can for instance retrieve the HTML for the menu or the page footer and insert it into your WordPress site. We don’t publish the values that you can use for the t= parameter here. Create a ticket if you need help.
Fetching data
URL structure for fetching data
For example:
The above call fetches contributors 1 to 50 as JSON data including galleries for each contributor.
Parameters
Which parameters you can use depends on what you are fetching. For data retrieval calls, the parameters page, max, order, desc, and lastid are always supported and defaults are used if omitted. I.e. the parameters are all optional. The order in which parameters appear is not important.
- format (string)
Defaults to “json”. Alternatively you can use “csv” for comma separated values text. - delimiter (string)
Defaults to a quote (char(34)). Only relevant if format=CSV. Delimiter can be one character only. - titles (integer)
Defaults to 0. Only relevant if format=CSV. Starts with a title row with column names if titles=1. - page (integer)
Page number, defaults to 1. If you retrieve data in blocks then add the parameter max. E.g. page=1&max=50 gets the first 50 rows. - max (integer)
Maximum number rows to retrieve. Cannot be larger than 1000 and also defaults to 1000 if omitted. - order (integer)
Depends on available options for a specific call. - desc (integer)
If 0 or omitted then data is sorted ascending. Use desc=1 to sort data in descending order. Note that if you fetch data in blocks (see max) then make sure to use the same sort order for subsequent calls. - lastid (integer)
Can be used to retrieve a block of data with rows that have an id greater than {lastid}. You can use this parameter for example if you are downloading data for storage in a local database or application. You can then fetch new rows periodically by specifying the last retrieved id that you locally stored.
JSON formatting
- Use the parameter format=json to fetch JSON formatted data. The data will be escaped as follows:
#8 (backspace) is \b
#9 (tab) is \t
#10 (line feed) is \n
#12 (form feed) is \f
#13 (carriage return) is \r
Quote (“) is escaped with a backslash e.g. \”
Backslash (\) is escaped with a backslash e.g. \\ - Furthermore
boolean values are returned as 1 (true) or 0 (false).
date/time values are formatted as yyyymmdd hh:nn e.g. 20180212 23:31
To learn about JSON, please visit www.json.org.
Fetching contributor data
To fetch contributor data, specify the value contributors for the get parameter. This command supports the following parameters in addition to the parameters described in the above paragraph with the heading Parameters:
- group (integer)
Defaults to 0 which means all groups are included. Specify a group id to fetch contributors belonging to a specific group only (e.g. group=139). - ownerid (integer)
Defaults to 0. If this parameter has a value, then only the contributor with the specified id is retrieved. - user (integer)
To retrieve contributors only if linked to a user account, add user=1. - localeid (integer)
To retrieve a specific language, defaults to 1 (English). - profile (integer)
Use profile=1 to retrieve only contributors that have a profile page. - galleries (integer)
Use galleries=1 to include data re the galleries that are linked to each contributor. Can only be used if format=JSON, galleries are in the data as an array. - linkedbygroup (integer)
Only relevant if galleries=1 is used. Defaults to 1 which means that all linked galleries are included for each contributor. You can link a contributor to a gallery group and to a gallery. If linkedbygroup=0 is used, then galleries that are linked via a gallery group are omitted. - crosslinked (integer)
Only relevant if galleries=1 is used. Defaults to 1 which means that all linked galleries are included for each contributor. If crosslinked=0 is used, then galleries that are linked via a cross linking are omitted. I.e. only galleries that exist in a group where the gallery was created will be included. - order (integer)
Specifies the sort order, which defaults to 0.
0=Group Id, Contributor Id
1=Contributor Id
2=Contributor name
3=Contributor date/time (creation)
4=Contributor sort name
You can use the parameter desc=1 to reverse the order (i.e. descending as opposed to ascending). - lastid (integer)
Defaults to 0. Use the last ownerid value to fetch new rows only (i.e. contributors with an id greater than lastid). - maxdesclen (integer) 31.2 or later
Defaults to 0 which means the full descriptions are in the dataset. Specify a number to truncate the descriptions, e.g. maxdesclen=50 - filecount (integer) 31.2 or later
Defaults to 0 which means that the galleries JSON array does not have the filecount property. Use filecount=1 to include this property
Note that you can also access certain gallery data in JSON format without using the ADS. To find out more about this, please read this article: Data feeds for galleries.
Fetching user data
To fetch user data, specify the value users for the get parameter. This command supports the following parameters in addition to the parameters described in the above paragraph with the heading Parameters:
- group (integer)
Defaults to 0. Add the group parameter to fetch users from a specific group only. - deleted (integer)
By default, deleted accounts are not included. Use deleted=1 to include deleted accounts. - disabled (integer)
By default, disabled accounts are not included. Use disabled=1 to include deleted accounts. - countryid (integer)
Defaults to 0. To filter for a specific country, use the parameter countryid with a valid number. - startdate (string)
Add the startdate parameter to filter for accounts created on or after the specified date. - enddate (string)
Add the enddate parameter to filter for accounts created on or before the specified date. Use both startdate and enddate to fetch rows created between the two dates. - order (integer)
Specifies the sort order, which defaults to 0.
0=last name
1=date/time (created)
2=last login date/time
3=organisation name - lastid (integer)
Defaults to 0. Use the last user id value to fetch new rows only (i.e. users with an id greater than lastid)
For information about other data/calls, create a ticket on xpertise.zendesk.com.
