Markup
The results for requests made to the emurestapi shim are returned marked up. The markup used is Mason a JSON based format for adding hypermedia elements, standardised error handling and additional metadata to JSON records. The Mason markup is constructed by taking a JSON record and merging hypermedia elements and other Mason features into it. In particular it provides a nice way of integrating linked data into JSON records.
The markup also defines what operations may be performed on the response’s data. For example whether a record and be deleted or modified. The markup also includes whether new records may be inserted or searches performed on the resource specified in the request. In fact, the REST API is Level 3 implementing HATEOAS (Hypermedia As The Engine Of Application State). Such an approach allows client software to provide UI feedback about the operations available at any given time.
The markup is embedded within a JSON record and also around the result set where more than a single record is returned. If an error is reported then it is returned in Mason format ensuring a consistent format that can be easily read by client software.
The amount of markup added to a result is controlled by the Prefer header. The representation value can have one of three settings:
- none - no markup should be added to the results
- minimal - descriptive elements are not not added
- full - all elements are added
The default value if a setting is not provided is full. For example, if you want to remove all markup then add the following HTTP header to your request:
Prefer: representation=none
An example of a record not marked up is:
{
"id": "emu:/museum/ecatalogue/1",
"version": 1,
"data": {
"AdmPublishWebNoPasswordFlag": "Y",
"ValValuationAmountOrig": 0,
"TitObjectRating": "Low",
"CreDateCreated": "1927",
"LocDateMoved": "2013-09-17",
"ExtendedData": "1\n[Building Structure] Object Accessioned\nOld Parliament House, Canberra, Australia",
"ValValuedByRef": "emu:/museum/eparties/27",
"LocIndependentlyMoveable": "Yes",
"SummaryData": "[Building Structure] \"Old Parliament House, Canberra, Australia\"",
"ValNextDue": "2008-08-17",
"ConConditionPeriodType": "Months",
"SecCanEdit_tab": [
"Group Default"
],
"SecCanDisplay_tab": [
"Group Default"
],
"TitNumberOfParts": 1,
"ValDateValued": "2007-08-17",
"ConCheckedByRef": "emu:/museum/eparties/28",
"PhyDescription": "Old Parliament House, Canberra, Australia",
"LocTimeMoved": "13:25:",
"LocCurrentLocationRef": "emu:/museum/elocations/1001589",
"AdmPublishWebPasswordFlag": "Y",
"LocReleasedByRef": "emu:/museum/eparties/23",
"CreEarliestDateOrig": 0,
"TitObjectStatus": "Accessioned",
"MulHasMultiMedia": "Y",
"TitPartNumber": 1,
"AdmPublishWebPassword": "Yes",
"TitMainTitle": "Old Parliament House, Canberra, Australia",
"AssIsParent": "Yes",
"ConConditionStatus": "Poor",
"ValValuationPeriod": 12,
"LocPermanentLocationRef": "emu:/museum/elocations/1000038",
"ConDateChecked": "2007-08-10",
"LocAcceptedByRef": "emu:/museum/eparties/23",
"MulMultiMediaRef_tab": [
"emu:/museum/emultimedia/212",
"emu:/museum/emultimedia/128",
"emu:/museum/emultimedia/130",
"emu:/museum/emultimedia/131",
"emu:/museum/emultimedia/132",
"emu:/museum/emultimedia/133",
"emu:/museum/emultimedia/136",
"emu:/museum/emultimedia/148",
"emu:/museum/emultimedia/147"
],
"irn": "emu:/museum/ecatalogue/1",
"CreEarliestDate": "1927",
"AdmTimeModified": "15:41:59",
"AccAccessionLotRef": "emu:/museum/eaccessionlots/1000088",
"ValValuationAmount": 440000.00,
"SecCanDelete_tab": [
"Group Default"
],
"AdmDateModified": "2019-04-11",
"AdmInsertedBy": "KE EMu Administrator",
"ConNextCheck": "2008-02-10",
"ConConditionPeriod": 6,
"CreLatestDateOrig": 0,
"ValReasonForValuation": "Possible Sale",
"AdmModifiedBy": "Philip Davies",
"ObjectType": "Object",
"ValValuationPeriodType": "Months",
"AdmTimeInserted": "16:58:34",
"TitObjectCategory": "Building Structure",
"CreLatestDate": "1927",
"LocRequestedByRef": "emu:/museum/eparties/31",
"AdmDateInserted": "2007-08-20",
"AdmPublishWebNoPassword": "Yes",
"CreCreationPlace1_grp": [
{
"CreCreationPlace1": "Oceania",
"CreCreationPlace2": "Australia",
"CreCreationPlace3": "Australian Capital Territory",
"CreCreationPlace4": "Canberra"
}
],
"AssRelatedPartiesRelationship_grp": [
{
"AssRelatedPartiesRef": "emu:/museum/eparties/8"
}
]
}
}
The same record with full markup is:
{
"id": "emu:/museum/ecatalogue/1",
"version": 1,
"data": {
"AdmPublishWebNoPasswordFlag": "Y",
"ValValuationAmountOrig": 0,
"TitObjectRating": "Low",
"CreDateCreated": "1927",
"LocDateMoved": "2013-09-17",
"ExtendedData": "1\n[Building Structure] Object Accessioned\nOld Parliament House, Canberra, Australia",
"ValValuedByRef": {
"id": "emu:/museum/eparties/27",
"@controls": {
"self": {
"href": "http://swanston.melbourne.axiell.com:8084/museum/eparties/27",
"title": "Resource record details",
"description": "Show the data for this resource record. The columns displayed is defined by the 'select' query parameter. If a selection is not defined then all columns will be retrieved."
}
}
},
"LocIndependentlyMoveable": "Yes",
"SummaryData": "[Building Structure] \"Old Parliament House, Canberra, Australia\"",
"ValNextDue": "2008-08-17",
"ConConditionPeriodType": "Months",
"SecCanEdit_tab": [
"Group Default"
],
"SecCanDisplay_tab": [
"Group Default"
],
"TitNumberOfParts": 1,
"ValDateValued": "2007-08-17",
"ConCheckedByRef": {
"id": "emu:/museum/eparties/28",
"@controls": {
"self": {
"href": "http://swanston.melbourne.axiell.com:8084/museum/eparties/28",
"title": "Resource record details",
"description": "Show the data for this resource record. The columns displayed is defined by the 'select' query parameter. If a selection is not defined then all columns will be retrieved."
}
}
},
"PhyDescription": "Old Parliament House, Canberra, Australia",
"LocTimeMoved": "13:25:",
"LocCurrentLocationRef": {
"id": "emu:/museum/elocations/1001589",
"@controls": {
"self": {
"href": "http://swanston.melbourne.axiell.com:8084/museum/elocations/1001589",
"title": "Resource record details",
"description": "Show the data for this resource record. The columns displayed is defined by the 'select' query parameter. If a selection is not defined then all columns will be retrieved."
}
}
},
"AdmPublishWebPasswordFlag": "Y",
"LocReleasedByRef": {
"id": "emu:/museum/eparties/23",
"@controls": {
"self": {
"href": "http://swanston.melbourne.axiell.com:8084/museum/eparties/23",
"title": "Resource record details",
"description": "Show the data for this resource record. The columns displayed is defined by the 'select' query parameter. If a selection is not defined then all columns will be retrieved."
}
}
},
"CreEarliestDateOrig": 0,
"TitObjectStatus": "Accessioned",
"MulHasMultiMedia": "Y",
"TitPartNumber": 1,
"AdmPublishWebPassword": "Yes",
"TitMainTitle": "Old Parliament House, Canberra, Australia",
"AssIsParent": "Yes",
"ConConditionStatus": "Poor",
"ValValuationPeriod": 12,
"LocPermanentLocationRef": {
"id": "emu:/museum/elocations/1000038",
"@controls": {
"self": {
"href": "http://swanston.melbourne.axiell.com:8084/museum/elocations/1000038",
"title": "Resource record details",
"description": "Show the data for this resource record. The columns displayed is defined by the 'select' query parameter. If a selection is not defined then all columns will be retrieved."
}
}
},
"ConDateChecked": "2007-08-10",
"LocAcceptedByRef": {
"id": "emu:/museum/eparties/23",
"@controls": {
"self": {
"href": "http://swanston.melbourne.axiell.com:8084/museum/eparties/23",
"title": "Resource record details",
"description": "Show the data for this resource record. The columns displayed is defined by the 'select' query parameter. If a selection is not defined then all columns will be retrieved."
}
}
},
"MulMultiMediaRef_tab": [
{
"id": "emu:/museum/emultimedia/212",
"@controls": {
"self": {
"href": "http://swanston.melbourne.axiell.com:8084/museum/emultimedia/212",
"title": "Resource record details",
"description": "Show the data for this resource record. The columns displayed is defined by the 'select' query parameter. If a selection is not defined then all columns will be retrieved."
}
}
},
{
"id": "emu:/museum/emultimedia/128",
"@controls": {
"self": {
"href": "http://swanston.melbourne.axiell.com:8084/museum/emultimedia/128",
"title": "Resource record details",
"description": "Show the data for this resource record. The columns displayed is defined by the 'select' query parameter. If a selection is not defined then all columns will be retrieved."
}
}
},
{
"id": "emu:/museum/emultimedia/130",
"@controls": {
"self": {
"href": "http://swanston.melbourne.axiell.com:8084/museum/emultimedia/130",
"title": "Resource record details",
"description": "Show the data for this resource record. The columns displayed is defined by the 'select' query parameter. If a selection is not defined then all columns will be retrieved."
}
}
},
{
"id": "emu:/museum/emultimedia/131",
"@controls": {
"self": {
"href": "http://swanston.melbourne.axiell.com:8084/museum/emultimedia/131",
"title": "Resource record details",
"description": "Show the data for this resource record. The columns displayed is defined by the 'select' query parameter. If a selection is not defined then all columns will be retrieved."
}
}
},
{
"id": "emu:/museum/emultimedia/132",
"@controls": {
"self": {
"href": "http://swanston.melbourne.axiell.com:8084/museum/emultimedia/132",
"title": "Resource record details",
"description": "Show the data for this resource record. The columns displayed is defined by the 'select' query parameter. If a selection is not defined then all columns will be retrieved."
}
}
},
{
"id": "emu:/museum/emultimedia/133",
"@controls": {
"self": {
"href": "http://swanston.melbourne.axiell.com:8084/museum/emultimedia/133",
"title": "Resource record details",
"description": "Show the data for this resource record. The columns displayed is defined by the 'select' query parameter. If a selection is not defined then all columns will be retrieved."
}
}
},
{
"id": "emu:/museum/emultimedia/136",
"@controls": {
"self": {
"href": "http://swanston.melbourne.axiell.com:8084/museum/emultimedia/136",
"title": "Resource record details",
"description": "Show the data for this resource record. The columns displayed is defined by the 'select' query parameter. If a selection is not defined then all columns will be retrieved."
}
}
},
{
"id": "emu:/museum/emultimedia/148",
"@controls": {
"self": {
"href": "http://swanston.melbourne.axiell.com:8084/museum/emultimedia/148",
"title": "Resource record details",
"description": "Show the data for this resource record. The columns displayed is defined by the 'select' query parameter. If a selection is not defined then all columns will be retrieved."
}
}
},
{
"id": "emu:/museum/emultimedia/147",
"@controls": {
"self": {
"href": "http://swanston.melbourne.axiell.com:8084/museum/emultimedia/147",
"title": "Resource record details",
"description": "Show the data for this resource record. The columns displayed is defined by the 'select' query parameter. If a selection is not defined then all columns will be retrieved."
}
}
}
],
"irn": {
"id": "emu:/museum/ecatalogue/1",
"@controls": {
"self": {
"href": "http://swanston.melbourne.axiell.com:8084/museum/ecatalogue/1",
"title": "Resource record details",
"description": "Show the data for this resource record. The columns displayed is defined by the 'select' query parameter. If a selection is not defined then all columns will be retrieved."
}
}
},
"CreEarliestDate": "1927",
"AdmTimeModified": "15:41:59",
"AccAccessionLotRef": {
"id": "emu:/museum/eaccessionlots/1000088",
"@controls": {
"self": {
"href": "http://swanston.melbourne.axiell.com:8084/museum/eaccessionlots/1000088",
"title": "Resource record details",
"description": "Show the data for this resource record. The columns displayed is defined by the 'select' query parameter. If a selection is not defined then all columns will be retrieved."
}
}
},
"ValValuationAmount": 440000.00,
"SecCanDelete_tab": [
"Group Default"
],
"AdmDateModified": "2019-04-11",
"AdmInsertedBy": "KE EMu Administrator",
"ConNextCheck": "2008-02-10",
"ConConditionPeriod": 6,
"CreLatestDateOrig": 0,
"ValReasonForValuation": "Possible Sale",
"AdmModifiedBy": "Philip Davies",
"ObjectType": "Object",
"ValValuationPeriodType": "Months",
"AdmTimeInserted": "16:58:34",
"TitObjectCategory": "Building Structure",
"CreLatestDate": "1927",
"LocRequestedByRef": {
"id": "emu:/museum/eparties/31",
"@controls": {
"self": {
"href": "http://swanston.melbourne.axiell.com:8084/museum/eparties/31",
"title": "Resource record details",
"description": "Show the data for this resource record. The columns displayed is defined by the 'select' query parameter. If a selection is not defined then all columns will be retrieved."
}
}
},
"AdmDateInserted": "2007-08-20",
"AdmPublishWebNoPassword": "Yes",
"CreCreationPlace1_grp": [
{
"CreCreationPlace1": "Oceania",
"CreCreationPlace2": "Australia",
"CreCreationPlace3": "Australian Capital Territory",
"CreCreationPlace4": "Canberra"
}
],
"AssRelatedPartiesRelationship_grp": [
{
"AssRelatedPartiesRef": {
"id": "emu:/museum/eparties/8",
"@controls": {
"self": {
"href": "http://swanston.melbourne.axiell.com:8084/museum/eparties/8",
"title": "Resource record details",
"description": "Show the data for this resource record. The columns displayed is defined by the 'select' query parameter. If a selection is not defined then all columns will be retrieved."
}
}
}
}
]
},
"@namespaces": {
"emu": {
"name": "http://axiell.com/emu#"
}
},
"@meta": {
"@title": "EMu Collections resource",
"@description": "Each of the EMu tables is mapped onto a resource. For example the EMu 'eparties' table maps to the 'emu:/{tenant}/eparties' resource. When a resource is manipulated the records stored in EMu are effected. Any EMu permissions set in the Registry are honoured though this API. The permissions aplied are those of the username associated with the token sent with each API request.",
"@controls": {
"help": {
"title": "API Documentation",
"description": "Displays the home page of the TexRestAPI documentation. The documentation contains indepth descriptions of the resources available along with the endpoints used to manipulate those resources.",
"href": "http://swanston.melbourne.axiell.com:8084/help/index.html"
}
}
},
"@controls": {
"self": {
"href": "http://swanston.melbourne.axiell.com:8084/museum/ecatalogue/1",
"title": "Resource record details",
"description": "Show the data for the curent resource record. The columns displayed is defined by the 'select' query parameter. If a selection is not defined then all columns will be retrieved."
},
"start": {
"method": "GET",
"href": "http://swanston.melbourne.axiell.com:8084/",
"title": "Home page",
"description": "The home page displays a list of all registered tenants. Once a tenant is selected access to its resources is available"
},
"emu:create": {
"method": "POST",
"href": "http://swanston.melbourne.axiell.com:8084/museum/ecatalogue",
"isHrefTemplate": true,
"encoding": "json",
"schemaUrl": "http://swanston.melbourne.axiell.com:8084/museum/resources/ecatalogue",
"title": "Create a new resource record",
"description": "A new resource record is created. The key number is assigned automatically. The key number corresponds to the IRN column in the JSON schema. Any default values and security defaults defined in the EMu Registry are set in the creatred resource record. The URI of the new record is returned in the 'Location' header."
},
"emu:insert": {
"method": "PUT",
"href": "http://swanston.melbourne.axiell.com:8084/museum/ecatalogue/{identifier}",
"isHrefTemplate": true,
"encoding": "json",
"schemaUrl": "http://swanston.melbourne.axiell.com:8084/museum/resources/ecatalogue",
"title": "Insert a new resource record",
"description": "Add a new resource record to the resource collection where you want to specify the key number. The key number corresponds to the IRN column in the JSON schema. Any default values and security defaults defined in the EMu Registry are set in the creatred resource record. Unlike the create function the URI of the new record is not returned in the 'Location' header."
},
"emu:replace": {
"method": "PUT",
"href": "http://swanston.melbourne.axiell.com:8084/museum/ecatalogue/1",
"encoding": "json",
"schemaUrl": "http://swanston.melbourne.axiell.com:8084/museum/resources/ecatalogue",
"title": "Replace the current resource record",
"description": "The current resource record's contents are replaced with record defined in the request's payload. A replace operation is effectively the same as deleting the existing record and then inserting the payload record using the same URI. In order to replace a record the delete permission is required on the current record and insert permission is required to create the new version. If only the contents of a record are to be updated then the 'emu:update' operation should be used."
},
"search": {
"method": "GET",
"href": "http://swanston.melbourne.axiell.com:8084/museum/ecatalogue",
"isHrefTemplate": true,
"schema": {
"properties": {
"filter": {
"type": "string",
"title": "Search criteria used when retrieving records",
"description": "Search criteria used when retrieving records. The 'filter' is optional and if not supplied then all records in the EMu resource defined by the request will be retrieved. A 'filter' consists of a top level JSON object containing a single property of eihter AND, OR or NOT. Each of these properties is an array of search conditions where a column name, operation and value is given. For complete details please consult the API Documentation."
},
"limit": {
"type": "integer",
"title": "Set number of records to retrieve",
"description": "If a large EMu collection is searched then the number of matching records may be very large. The 'limit' query parameter allows the number of records to return to be set. The response will contain a 'Next-Search' header if there are more records available for retrieval. A future request containing the header will return the next set of matching records. Using such an approach, it is possible to provide pages of results."
},
"select": {
"type": "string",
"title": "List columns to be viewed",
"description": "A semi-colon separated list of column names determines what data is retrieved for each matching record. The column names are those defined in the matching records, that is they are prefixed with the 'data.' column."
},
"sort": {
"type": "string",
"title": "Sort matching records",
"description": "A sort order may be defined for records matching the search criteria. The sort is a JSON array where each entry is a JSON object defining the column name on which to sort and the 'order', that is ascendign or descending order. See the API Documentation for a full description of the sort format."
}
}
},
"title": "Search the resource collection",
"description": "Search an EMu collection by applying a set of search criteria. The search clause is defined by the 'filter' query parameter using a JSON based query language. For details of the language see the API Documentation. The matching records may be sorted using the 'sort' query parameter while the columns retrieved may be limited through the 'select' query parameter. The matchign records are returned in the 'matches' JSON array in the response. Each matching record can be retrieved by its 'self' operation."
},
"emu:update": {
"method": "PATCH",
"href": "http://swanston.melbourne.axiell.com:8084/museum/ecatalogue/1",
"encoding": "json",
"schemaUrl": "http://json.schemastore.org/json-patch",
"title": "Update the current resource record",
"description": "An update operation allows values the current record to be modified. A JSON Patch (RFC 6902) object is sent in a request payload detailing changes to be made to the current record. The changes are applied and the record is then saved, provided it passes validation. The EMu update permission is required to be able to alter a record."
},
"emu:delete": {
"method": "DELETE",
"href": "http://swanston.melbourne.axiell.com:8084/museum/ecatalogue/1",
"title": "Delete the current resource record",
"description": "The resource record displayed is deleted. The record is permanently removed from the resource collection. Once a record has been removed it is no longer retrievable. The delete operation is final and cannot be reversed."
}
}
}
Notice that links to other records are now expanded to include the URI used to retrieve the record (look for the @controls property). Also there is a @controls section at the end detailing the operations currently available along with the URI required to execute the operation.
If an error occurs then the Mason marked up reason is returned:
{
"@error": {
"@code": "NoMatch",
"@message": "Cannot retrieve emu:/museum/ecatalogue/10000",
"uri": "emu:/museum/ecatalogue/10000",
"@httpStatusCode": 404
}
}
The error format is consistent allowing client software to easily interpret it and display a useful error message.
When a single record is returned as the result of a request the record is encased in an envelope containing three properties:
- id - URI used to identify the record
- version - current version number of the record
- data - JSON containing the record data itself
The record below shows the structure returned for a single record. The record is displayed without markup where representation=none is specified in the HTTP header:
{
"id": "emu:/museum/eparties/718",
"version": 1,
"data": {
"NamFirst": "Christine"
}
}
If more than a single record is returned then a JSON matches array is found at the outer level with each record marked up as an element in the array. The results below show a set of five matches without markup:
{
"matches": [
{
"id": "emu:/museum/eparties/718",
"version": 1,
"data": {
"NamFirst": "Christine"
}
},
{
"id": "emu:/museum/eparties/102476",
"version": 1,
"data": {
"NamFirst": "Bill"
}
},
{
"id": "emu:/museum/eparties/103139",
"version": 1,
"data": {
"NamFirst": "Kenneth"
}
},
{
"id": "emu:/museum/eparties/103178",
"version": 1,
"data": {
"NamFirst": "Ray"
}
},
{
"id": "emu:/museum/eparties/721",
"version": 1,
"data": {}
}
]
}
The Content-Type: header for response data is:
application/vnd.mason+json; charset=UTF-8
where the data has been marked up with Mason. If the data has not been marked up then the Content-Type: header is:
application/json; charset=UTF-8