The TUNE API is a web service that defines a set of data interactions to its reports and other scripts. This web service is a collection of network Endpoints, each represented by a simple HTTP URL string. Most endpoints access reports via the web service's content, which typically comprises reports generated by data pulled from Records.
An Endpoint is based on an abstract definition, and can be either a "generic" or "data consumer" endpoint:
- Data consumer endpoint represents a connection point for querying a specific record for generating reports. Most of these endpoints have read/write functionality to create/update/delete datasets from their associated records, but some only have read-only functionality.
- Generic endpoint represents a connection point to a read-only service of a non-specific type, not bound to a record, and receives data that is of primitive types (such as string or integer).
A Record represents a table in a database with fields defined by:
- Field name
- Property type - 'string', 'integer', 'choice', 'reference', etc...
- Default value [optional]
- Required [default not required] - Upon saving a new dataset, if this field is required, then a value must be provided.
- Choices - If property type is 'choice', then a list of allowed values is assigned.
- Nicename [optional] - Humanized wording for this field.
It is important to note the Property type 'reference', which is an identifier to a related Record of another type. There can be multiple 'reference' fields, each uniquely associated with different Record types, including itself.
Endpoints accessing Records
A data consuming Endpoint is associated with only one Record. It defines what and how information from its record is consumable by users. When an Endpoint is requested to generate a report by pulling datasets from its record, the Endpoint defines record fields that are:
- Provided by default.
- Extra and must be specifically requested.
- Aggregated results across multiple datasets.
When requesting an Endpoint to generate a report, the fields to define the report uses the same name as its associated Record's fields.
Related Endpoints and Record's Referenced Records
If a data consuming Endpoint is associated with a Record that has one or more fields referencing other Records, then in turn it has Related Endpoints that are associated with those referenced Records. As with a Record with 'reference' fields as identifiers to a unique set of related Record types, then so are the set of Related Endpoints of that Endpoint (associated with said Record).
For identification of Related Endpoints, an Endpoint assigns each Related Endpoint with a unique property name, which is used when a report request is to include content from its Related Endpoints' fields. If an Endpoint associated with a Record does not have 'reference' fields, then that Endpoint does not have any Related Endpoints.
Related Endpoints of an Endpoint define access to their Related Records.
An action is an abstract description of an operation supported by an Endpoint, which can have one or more actions.
- Actions of a Data consumer endpoint request reports/results by preparing a query to its bound Records, and possibly including its Related Endpoints.
- Actions of a Generic endpoint request information from a service that is not data bound to any Record.
Most Data consumer endpoints have in common a set of base actions for querying and updating their bound Records (for example, 'count', 'find', 'save', 'delete', 'validate', and 'get'). An action receives requests via the query string portion of an endpoint URL. The contents of the query string must abide by the parameter signature of an action (or it will be rejected), which includes matching parameter naming, matching parameter type, and provide all required parameters. If the contents of the query string are valid, then the action makes a request to its sources. Upon completion, a response is provided based on the requested result format (JSON by default).