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:

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:

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:

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:

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:

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:

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:

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:

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"}[/code]

<*> or "dataSourceReference": {           "uri": "/datasources/JServerJNDIDS"       },[/code]                    

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.

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"}[/code]                    

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.