The v2/resources Service

The REST v2/resources service replaces the original resource and resources services to search the repository and access the resources it contains. This new service provides greater performance and more consistent handling of resource descriptors for all repository resource types. The service has two formats, one takes search parameters to find resources, the other takes a repository URI to access resource descriptors and file contents.

V2 Resource Descriptors

The v2/resources service introduces new resource descriptors for nearly all repository objects. This section introduces the features of the new descriptors, and the next section, The v2/resources Service, lists all the descriptors and the specific attributes of each.

Resource IDs

The ID of a resource is its unique name within the folder where it resides. Resource descriptors do not have an explicit ID attribute, but the ID is always the last component of the URI field in responses from the server.

When sending resource descriptors in requests, the URI field is ignored. The URI and ID of a created resource is determined in one of the following ways:

POST operations on the v2/resources service specify a folder. The resource descriptor in the request is created in the specified folder. The ID is created automatically from the label of the resource by replacing special characters with underscores (_). The URI of the new resource is returned in the server's response and consists of the target folder with the automatic ID appended to it.
PUT operations on the v2/resources service send a descriptor to create the resource at the URI specified in the request. The resource ID is the last element of this URI, as long as it is unique in the parent folder. The server's response should confirm that the resource was successfully created with the requested URI.

Custom Media Types

In order to specify all the different types of resources, the v2/resources service relies on custom media types with the following syntax:

application/repository.<resourceType>+<format>

where:

<resourceType> is the name for each type of repository resource, such as reportUnit, dataType, or jdbcDataSource. The names of all supported types are given in The v2/resources Service.
<format> is the representation format of the descriptor, either json or xml.

For example:

application/repository.dataType+json - JSON representation of a datatype resource

application/repository.reportUnit+xml - XML representation of a JRXML report

The custom media types should be used in Content-Type and Accept HTTP headers, as described in the following sections. According to the HTTP specification, headers should be case insensitive; the headers and custom media types can be upper case, lower case, or any mixture of upper and lower case.

Accept HTTP Headers

Client applications should use the Accept HTTP header in a request to specify the desired format in the server's response. Generally, regardless of the resource type, it's enough to specify:

Accept: application/json to get response in JSON format or
Accept: application/xml to get response in XML fomat.

The server will respond with the specific custom media type for the requested resource, as described in the next section.

However, there are some special cases where client must specify a precise resource type:

When requesting the resource details of the root folder, client must specify application/repository.folder+<format> to get its resource descriptor. Otherwise, the request is considered a search of the root folder.
When requesting the resource details of a file resource, as opposed to the file contents, the client must specify application/repository.file+<format>. Without this Accept header, the response will contain the file contents. The custom media type also distinguishes between the XML descriptor of a file and the contents of an XML file.

If the client specifies a custom type in the Accept header that does not match the resource being requested, the server responds with the error code 406 Not Acceptable.

Content-Type HTTP Headers

The Content-Type HTTP header indicates the media type being sent in the body of the request or response. For example, if the client requests a valid datatype resource, and depending on the format that the client specified in the Accept header of the request, the server's response includes:

Content-Type: application/repository.dataType+json or
Content-Type: application/repository.dataType+xml

When the client uploads a resource descriptor to create or update a resource, it must set the Content-Type connector accurately. For example, when uploading a datatype resource represented in XML, the client must send:

Content-Type: application/repository.dataType+xml

The server relies on the Content-Type header to parse the body of the request, and it will respond with the error code 400 Bad Request if there is a mismatch. In the example above, the following headers will result in an error:

Content-Type: application/xml - custom media type not included
Content-Type: application/repository.reportUnit+xml - media type mismatch
Content-Type: application/repository.dataType+json - format mismatch

JSON Format

JasperReports Server uses the standard JSON (JavaScript Object Notation) format to send and receive representations of resources and other structures. The JSON marshalling and unmarshalling (parsing) uses the following conventions:

Attributes with no value or a null value are not transmitted in a request.
Unknown properties that JasperReports Server does not recognize are ignored without error.
Dates should be given in ISO 8601 format.

Nested Resources

Many types of resources in the repository are defined in terms of other resources. For example, some types of input controls require a query, and the query itself requires a data source. The nested query and data source can be defined in two ways:

Referenced resources - a link to a valid resource defined elsewhere in the repository. JasperReports Server manages the references between resources by enforcing permissions and protecting dependencies from deletion.
Local resources - a resource descriptor nested within the parent descriptor. The nested resource is fully defined within the parent resource and not available for being referenced from elsewhere.

Both types of nested resources are further described in the following sections.

Referenced Resources

Referenced resources are defined by special structures within the descriptors of other resources. For example, in the following query resource, the data source field contains a dataSourceReference object that contains the URI of the target reference:

{
    "version": 0,
    "permissionMask": 1,
    "creationDate": "2013-10-03T16:32:37",
    "updateDate": "2013-10-03T16:32:37",
    "label": "Country Query",
    "description": null,
    "uri": "/adhoc/topics/Cascading_multi_select_topic_files/Country_multi_select_files/
            country_query",
    "dataSource": { contents }, <*>
    "value": "select distinct billing_address_country from accounts order by billing_address_country",
    "language": "sql"
}
<*> or "dataSourceReference": {
           "uri": "/datasources/JServerJNDIDS"
       },

To create referenced resources, send requests to the server that contain the appropriate reference objects for the target resource. See the The v2/resources Service for the specific reference objects available in each resource descriptor.

When reading resources with referenced resources, the uri attribute gives the repository URI of the reference. To simplify the parsing of referenced resources, the v2/resources service GET method supports the expanded=true parameter. Instead of following references and requiring two or more GET requests, the expanded=true parameter returns all referenced resources fully expanded within the parent resource, as if it were a local resource.

The following resource types support referenced resources, and the table gives the name of the field that contains the referenced URI, and the name of the expanded type that replaces the reference.

Resource Type

Reference Attribute(s)

Expanded Name and Descriptor

query

dataSourceReference

awsDataSource, beanDataSource, customDataSource, jdbcDataSource, jndiJdbcDataSource, virtualDataSource, semanticLayerDataSource or advDataSource (adhocDataView)

inputControl

datatypeReference
listOfValuesReference
queryReference

dataType
listOfValues
query

reportUnit

jrxmlFileReference
dataSourceReference
queryReference
inputControlReference
fileReference (images, ...)

jrxmlFile with file attributes
see query dataSourceReference
query
inputControl
fileResource with file attributes

semanticLayerDataSource
(Domain)

dataSourceReference
schemaFileReference
fileReference (bundle)
securityFileReference

see query dataSourceReference
schemaFile with file attributes
file of appropriate type
securityFile with file attributes

olapUnit

olapConnectionReference

xmlaConnection,
mondrianConnection,
or secureMondrianConnection

mondrianConnection

dataSourceReference
schemaReference

see query dataSourceReference
schema with file attributes

secureMondrianConnection

dataSourceReference
schemaReference
accessGrantSchemaReference

see query dataSourceReference
schema with file attributes
accessGrantSchema with file attributes

mondrianXmlaDefinition

mondrianConnectionReference

mondrianConnection
or secureMondrianConnection

Local Resources

Nested resources that are not referenced resources must be defined locally within the parent resource. The nested resource is defined by a complete resource descriptor of the appropriate type. The following example shows a data source that is defined locally within the parent query resource:

{
    "version": 0,
    "permissionMask": 1,
    "creationDate": "2013-10-03T16:32:37",
    "updateDate": "2013-10-03T16:32:37",
    "label": "Country Query",
    "description": null,
    "uri": "/adhoc/topics/Cascading_multi_select_topic_files/Country_multi_select_files/country_query",
    "dataSource": {
        "jndiJdbcDataSource": {
            "version": 0,
            "permissionMask": 1,
            "creationDate": "2013-10-03T16:32:05",
            "updateDate": "2013-10-03T16:32:05",
            "label": "my JNDI ds",
            "description": "Local JNDI Data Source",
            // URI of expanded nested resource is ignored. Resource is created locally
            "uri": "/datasources/JServerJNDIDS",
            "jndiName": "jdbc/sugarcrm",
            "timezone": null
        }
    },
    "value": "select distinct billing_address_country from accounts order by billing_address_country",
    "language": "sql"
}

Use nested descriptors such as the ones above to create resources that contain local resources. Descriptors can be nested to any level, as long as the syntax of each descriptor is valid. See The v2/resources Service for the correct syntax of both the parent and the nested resource.

Internally, the v2/repository service handles local resources as normal resources contained in a hidden folder. The hidden folder containing local resources has the following name:

<parentURI>_files/

and local resources can be accessed at the following URI:

<parentURI>_files/<resourceID>

In the example above, we can see that the parent query resource is a nested resource itself. Its URI shows us that it is the query resource for a query-based input-control of a topic resource:

/adhoc/topics/Cascading_multi_select_topic_files/Country_multi_select_files/country_query

and the new nested data source will have the following URI:

/adhoc/topics/Cascading_multi_select_topic_files/Country_multi_select_files/country_query_files/my_JNDI_ds

The ID of the nested resource (my_JNDI_ds) is created automatically from the label of the nested resource.

The _files folder that exists in all parents of local resources is hidden so that its local resources do not appear in repository searches. You can set the showHiddenItems=true parameter on the v2/resources request to search a _files folder for all local resources, such as in a JRXML report (reportUnit).

Local resources in the hidden _files folder can also be created and updated separately from their parent resources by using PUT and POST methods of the v2/resources service and specifying the complete URI of the local resource as shown above.

Optimistic Locking

The v2/resources service supports optimistic locking on all write and update operations (PUT, POST, and PATCH). When using the service to search the repository and receive descriptors of the resources, all descriptors contain a version number field. Clients should return the same version number when writing or updating a given resources. The server compares the version number in the modify request the current version of the resource to assure that no other client has updated the same resource.

If the version numbers do not match, the server replies with error code 409 Conflict. In that case, the client should request the resource again (read operation with GET) and send the modify request with an updated version number.

When a modify operation is successful, the server increments the version number on the affected resource and returns the new descriptor with the new version as confirmation that the operation was successful.

Update-only Passwords

Some resource descriptors such as jdbcDataSource and xmlaConnection contain a password field. All password fields are blank or missing when reading (GET) a resource descriptor. This prevents anyone, even administrators from seeing existing passwords.

Write or update operations (PUT or POST) may send the password field in descriptors that support it. In this case, the password value is updated in the resource in the repository. Make sure that resources with sensitive passwords have the proper permissions so that only authorized users can modify them.

Version: 
Feedback