JSON Query Interface
The Tizra JSON interface allows a lot of information to be pulled from the Tizra system in JSON format, for easy manipulation by browsers. These calls are meant to be used in site implementations when called by javascripts from the a user's browser; they are not intended as administrative interfaces. While the data formats (and underlying interface code) are shared with the administrative interfaces for consistency, information on=the queried objects is filtered.
The api is accessed from a site URL which may be the live site URL, or a Staging or Test site URL. In the case of published objects, the returned information will reflect the state of that object on the staging or live, as determined by the name of the server. This means that relative URLs should be used to fetch JSON information relating to the the appropriate version of the site. There are a limited number of pages that are delivered by the secure server (account information delivered via https in response to an account update or credit card operation, for instance). If you are scripting such pages, the page base URL will not be appropriate. For these pages javascript can be included on the page to set base URL using the Tizra macros, as described in the solution to an old Tizra navigation link issue. While the macros will work on every page, often the relative URL solution will suffice and make for more readable markup.
Individual items in search or other API results may happen to be null. This can happen due to update anomalies and/or transient conditions; code that uses the search APIs should be aware of this and not crash.
Query strings are used to select objects for information retrieval. The API currently is read-only, returning information about various objects in a Tizra site.
For security reasons, the Tizra API will not expose fields to JSON that are completely hidden from users, except for a few explicit exceptions (like the BypassToC field, which is non-sensitive, and useful for controlling displays and links). This prevents the inadvertent leakage of internal system information, and allows sites to include metadata that is not appropriate for end users to see. If such fields were available via JSON anyone could see them simply by reading the javascript for a page, and then issuing their own JSON calls.
However, it is often useful to hide a rarely used or very large field from list views and show it on demand when the user clicks on a link. The list view delivers all visible fields, leaving it to javascript and CSS to determine which fields are visible.
We've seen significant performance improvements by using JSON to fetch these large or rarely-needed properties on demand when the user clicks. Once the Ajax delivery completes, the browser modifies the markup on the fly, and the user sees the information. With observed JSON response times under 50ms for a typical abstract, this performs really well!
To hide a property from visibility in list blocks you need to uncheck the "show to user" flag on the property. That will also hide the field from JSON (defeating the purpose). The way around this is to also make that field "Show in Search" which will add that field to the advanced search dialog (fine for an abstract, for instance).
This was first implemented in the as a response to User issue 79..
-
tizra-id: The id for a tizra-managed object is represented by a short string of numbers and letters. These IDs are visible in the admin interface, and in exports from Tizra.
-
url-id: This is the custom URL for an object, or alternatively the tizra-id of an object.
-
db-id: This is a number representing a Tizra object -- equivalent to the tizra-id, but sometimes convenient. Also displayed in the administrative interface.
-
meta-type: some queries can be limited by the meta-type of the object (objects with meta-types are content objects like pages, documents, excerpts, and offers, which are access-controlled and can be delivered directly to users). Some other objects, like Licenses, do not have meta-types and must be selected by other means.
These parameters are used to limit the information returned either about a single object, or about each of the objects in a list. All Tizra objects are represented as hashes with fields. Objects with meta-types also have user-defined properties. The properties of an object are represented as a hash contained in the "props" field. Normally all properties for an object are returned, but the results can be limited to those contained in a specific list.
-
fields: By defaults, all results return all fields that exist for an object. This parameter allows limiting the results to named fields. This parameter takes a field to be displayed in the result as its value. The field can be repeated if more than one field should be included in the result, so that a query string like:
?fields=url-id&fields=tizra-idwould filter results to include only the custom URL and tizra-id. -
props: This parameter can repeat in the same way as the
fieldsparameter can, but it filters the items contained in thepropsfield of the object. The props field will automatically be included if property filtering is on.
When a list is too long, it is paged. The following two items can be used to manually adjust list delivery if desired. Because of the need to prevent potential problems and manage performance, lists may be shorter than requested, even if additional items exist. It is not necessary to use these parameters or arithmetic to retrieve a list, since list results include a URL for the next chunk.
- limit: number of items to include in a list result as a maximum.
- start: zero-based starting item index of the list to return. (i.e. the first item is 0, the fourth item is 3).
List results all take the form of a hash with a result field containing an array of the results. If the list has been paginated, there will also be a next field. The contents of the next field are a relative URL of the next set of results for the query. The form of these URLs may change over time, and next will always contain the preferred url to get the rest of a query result.
All operations are relative to the site host name. This means that relative URLs can be used to access the staging or live version of a site as appropriate. Like links to graphics assets, this approach will not work on the small number of pages accessed via secure URLS.
-
/api/This is the root operation, and returns a JSON description of the operations available on the site, and the parameters that can be passed to them. -
/api/query/Looks up a particular object based on itstizra-id,url-idordb-id. If none of those are specified, butmeta-typeis specified, returns a list of all objects with the specified meta-type. -
/api/query/attachmentsLooks up a particular object based on itstizra-id,url-idordb-id. returns a list of the attachments to this object. -
/api/query/excerptsLooks up a particular object based on itstizra-id,url-idordb-id. returns a list of excerpts from this object. If no object is specified, returns a list of all excerpts on the entire site. -
/api/query/contentsLooks up a particular object based on itstizra-id,url-idordb-id. The object named should be a collection. Returns a list of the contents of this collection. -
/api/query/collectionsreturns a list of all collections on the site. -
/api/query/publicationsreturns a list of all publications ("Books") on the site. -
/api/query/logged-in-usersreturns a list of all user accounts logged onto the site for this session, with their associated information. -
/api/query/licensesreturns a list of all active licenses for user accounts logged into the site for this session. This includes account and group information associated with each identity. -
/api/query/matchreturns a list of all objects with a certain meta-type, that match a particular value. Calls to match must specify the parametersmatch-prop,match-valueandmeta-type. The value of meta-type must be an exact match for the meta-type of the given object; being a supertype is not enough. -
/api/query/table-of-contentsreturns a list of table of contents entries for a given object. If the extra parameterlink-excerpt-fieldthe value is regarded as the name of a property on the bookmark which should be used to fetch theurl-idandis-freeflag for that excerpt and add that information to the table of contents entry record. -
/api/searchExecutes a full Tizra search against the site. Results are paginated, and additional repeatable arguments (fieldandvalue) specify the names and values of the properties to be searched. More complex search parameters are possible with the use of JSON arguments via the POST method of this interface. -
/api/prop-valuesFind values for a given field, as limited by metatype and/or search constraints. Some value search constraints require the use of JSON arguments via the POST method of this interface. The basic specification includes these query parameters:meta-type: limits the type of objects whose values are examined;full-info=truereturns an array of records containing the value, as well as the count of each field value;prop-names: repeatable parameter naming the field values desired;prefix: a string that limits the resulting values. -
/api/type-inforeturns a record associating the name of each meta-type defined for the site with a map of the properties defined on that type, and their data types and indexing characteristics. This a decent chunk of pretty static information and is probably better cached than repeatedly queried.
The API is self-describing, so that the version can be checked and code can behave appropriately. The version numbers use semantic versioning:
-
Changes in the last digit reflect bug fixes, and should be compatible with no changes to correct client code.
-
Changes in the second digit reflect upward-compatible changes or fixes, where old code should continue to work but changes may be needed to take advantage of new features.
-
Changes in the first digit imply larger changes that will require some re-work of client code.
http://www.example.com/api/
will return a description of the methods allowed. This is in the form of a JSON record describing the URLS and parameters that make up the API, and the version of the API implemented by the server.
{
"tizra-api-version": "1.4",
"operations": [
{
"description": "query properties of a given object, specified by tizra-id or url-id, and\nfiltered by 'props' (metadata properties) or 'fields' (system defined properties)",
"href": "/api/query",
"operation": "query-object",
"params": [
"tizra-id",
"url-id",
"db-id",
"props",
"fields"
]
},
{
"description": "list the attachments of an object",
"href": "/api/query/attachments",
"operation": "attachments",
"params": [
"tizra-id",
"url-id",
"db-id",
"start",
"limit"
]
},
{
"description": "list excerpts from a given object",
"href": "/api/query/excerpts",
"operation": "excerpts",
"params": [
"tizra-id",
"url-id",
"db-id",
"props",
"fields",
"start",
"limit"
]
},
{
"description": "list the contents of an object (a collection)",
"href": "/api/query/table-of-contents",
"operation": "table-of-contents",
"params": [
"tizra-id",
"url-id",
"url-id",
"link-excerpt-field"
]
},
{
"description": "list the contents of an object (a collection)",
"href": "/api/query/contents",
"operation": "contents",
"params": [
"tizra-id",
"url-id",
"db-id",
"props",
"fields",
"start",
"limit",
"sort-prop"
]
},
{
"description": "get a list of all objects with a specified meta type.",
"href": "/api/query/",
"operation": "query-by-type",
"params": [
"meta-type",
"props",
"fields",
"start",
"limit",
"sort-prop"
]
},
{
"description": "get a list of all objects with that match a specified value for a property",
"href": "/api/query/match",
"operation": "match",
"params": [
"meta-type",
"props",
"fields",
"start",
"limit",
"sort-prop",
"match-prop",
"match-value"
]
},
{
"description": "get a list of all collections.",
"href": "/api/query/collections",
"operation": "collections",
"params": [
"props",
"fields",
"start",
"limit",
"sort-prop"
]
},
{
"description": "get a list of all publications.",
"href": "/api/query/publications",
"operation": "publications",
"params": [
"props",
"fields",
"start",
"limit",
"sort-prop"
]
},
{
"description": "execute a search.",
"href": "/api/search",
"methods": [
"GET",
"POST"
],
"operation": "publications",
"params": [
"meta-type",
"props",
"fields",
"field",
"value",
"start",
"limit",
"sort-prop"
]
},
{
"description": "Find values for a given field, as limited by metatype and/or search constraints.\nFull search constraints require use of the POST interface.",
"href": "/api/prop-values",
"methods": [
"GET",
"POST"
],
"operation": "publications",
"params": [
"meta-type",
"prop-names",
"prefix",
"full-info"
]
},
{
"description": "get a list of all excerpts.",
"href": "/api/query/excerpts",
"operation": "excerpts",
"params": [
"props",
"fields",
"start",
"limit",
"sort-prop"
]
},
{
"description": "get a list of all logged-in users associated with the current session.",
"href": "/api/query/logged-in-users",
"operation": "logged-in-users",
"params": [
"start",
"limit"
]
},
{
"description": "get a list of all logged-in users associated with the current session,\n and all licenses those users hold, including group information.",
"href": "/api/query/licenses",
"operation": "licenses",
"params": [
"start",
"limit"
]
}
],
"href": "/api/",
"parameters": {
"db-id": {
"description": "numerical database id for a an object",
"name": "db-id"
},
"descending": {
"description": "boolean value as to direction of sort.",
"name": "descending",
"repeatable": false
},
"field": {
"description": "Name of the property to search on",
"name": "field"
},
"fields": {
"description": "the names of any top level fields to be included in the results.\n Names not listed here will not be included in the results, except that if a props value is specified\nthe props field will be included automatically.",
"name": "fields",
"repeatable": true
},
"full-info": {
"description": "Boolean: (used for 'prop-values operation). True means include counts of matching items for each value listed.",
"name": "full-info"
},
"limit": {
"description": "maximum number of items desired in a list result. Fewer results may\nbe returned, even if more are available, to limit system resources used in satisfying a request.",
"name": "limit"
},
"meta-type": {
"description": "The name of a Tizra meta type for objects.",
"name": "meta-type"
},
"prefix": {
"description": "prefix that should be matched the values retrieved.",
"name": "prefix"
},
"prop-names": {
"description": "Name of the property whose values are being looked up. Repeatable.",
"name": "prop-names"
},
"props": {
"description": "the names of any metadata properties to be included in the results.\n Names not listed here will not be included in the results.",
"name": "props",
"repeatable": true
},
"sort-prop": {
"description": "the name of a property to be used to sort the results.",
"name": "sort-prop",
"repeatable": false
},
"start": {
"description": "Zero-based starting offset for results of a list query.",
"name": "start"
},
"tizra-id": {
"description": "alphanumerical Tizra identifier for an object",
"name": "tizra-id"
},
"url-id": {
"description": "The url component for an object -- either a tizra-id, or the custom URL, if one exists.",
"name": "url-id"
},
"value": {
"description": "Value of the property to be searched for",
"name": "value"
}
}
}