Library Application service

Through the REST API, the Library Application API allows clients to read application metadata and RAP files from the library, upload new applications, and update or delete existing applications.

This page contains the following information:

Client code sample

To use the Library Application service, send requests by making calls with the required HTTP methods. See the following base URL for this service:

  <host>/Relativity.REST/API/Relativity.LibraryApplications/workspace/-1/libraryapplications/

Note: For the workspace identifier in the URL, use -1 to indicate the admin-level context. This value is required for all URLs in the Library Application service. For additional guidelines, see Library Application API.

CreateAsync

To create a library application, send a POST request using multi-part form data. The first part should contain the request as JSON content type application/json. The second part should contain the file as binary with content type application/octet-stream:

https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{packageGuid}

Note: The alternative version takes a GUID referring to a previously uploaded package, see UploadPackage. The body is empty.

The body of the request is empty.

The response contains the following fields for the library application:

  • ApplicationIdentifier - the identifier of the application.
    • ArtifactID - the Artifact ID of the library application.
    • Guids - an array of GUIDs used to identify the library application.
  • Actions - an array of Action objects indicating operations that you have permissions to perform on this library application. For example, you may not have permissions to modify a library application due to your privileges. Each Action object contains the following fields that are available as extended metadata:
    • Name - name of an operation available through REST for the library application, such as delete, update, and so on.
    • Href - the URL used to make an HTTP request for the operation.
    • Verb - the name of the HTTP method for the operation.
    • IsAvailable - a Boolean value indicating whether the operation is available or not on this library application.
    • Reason - provides an explanation for the unavailability of an action.
  • ApplicationInstallID - the ID of the application installation.
  • InstallStatus - the status of the application installation.
    • Code - the status code indicating the state of the application installation.
    • Message - a string that returns an informative message about the status of the request.

ReadAsync

To read a library application, send a GET request for any one of the following URLs:

https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/{includeMetadata}/{IncludeActions}
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/{includeMetadata}/{IncludeActions}

The body of the request is empty.

The response contains the following fields for the library application:

  • Version - the version of the library application.
  • FileName - RAP file name of the library application.
  • UserFriendlyURL - a more simple and readable version of the application's URL (i.e. without GUIDs).
  • Required - whether an application is required, required if present or optional.
  • TreeView - indicates the different components that make up the application in JSON format.
  • CreatedBy - contains the Artifact ID and name of the user who created the library application.
  • CreatedOn - the date and time when the library application was added to Relativity.
  • LastModifiedBy - contains the Artifact ID and name of the user who recently updated the library application.
  • LastModifiedOn - the date and time when the library application was most recently modified.
  • Actions - an array of Action objects indicating operations that you have permissions to perform on this library application. For example, you may not have permissions to modify a library application due to your privileges. Each Action object contains the following fields that are available as extended metadata:
    • Name - name of an operation available through REST for the library application, such as delete, update, and so on.
    • Href - the URL used to make an HTTP request for the operation.
    • Verb - the name of the HTTP method for the operation.
    • IsAvailable - a Boolean value indicating whether the operation is available or not on this library application.
    • Reason - provides an explanation for the unavailability of an action.
  • Name - the name of the library application.
  • ArtifactID - the Artifact ID of the library application.
  • Guids - an array of GUIDs used to identify the library application.

ReadAllAsync

To read all library applications, send a GET request for one of the following URLs:

https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{includeMetadata}/{includeActions}

The body of the request is empty.

The response contains the following fields for the library application:

  • Version - the version of the library application.
  • FileName - RAP file name of the library application.
  • UserFriendlyURL - a more simple and readable version of the application's URL (i.e. without GUIDs).
  • Required - whether an application is required, required if present or optional.
  • TreeView - indicates the different components that make up the application in JSON format.
  • CreatedBy- contains the Artifact ID and name of the user who created the library application.
  • CreatedOn - the date and time when the library application was added to Relativity.
  • LastModifiedBy - contains the Artifact ID and name of the user who recently updated the library application.
  • LastModifiedOn - the date and time when the library application was most recently modified.
  • Actions - an array of Action objects indicating operations that you have permissions to perform on this library application. For example, you may not have permissions to modify a library application due to your privileges. Each Action object contains the following fields that are available as extended metadata:
    • Name - name of an operation available through REST for the library application, such as delete, update, and so on.
    • Href - the URL used to make an HTTP request for the operation.
    • Verb - the name of the HTTP method for the operation.
    • IsAvailable - a Boolean value indicating whether the operation is available or not on this library application.
    • Reason - provides an explanation for the unavailability of an action.
  • Name - the name of the library application.
  • ArtifactID - the Artifact ID of the library application.
  • Guids - an array of GUIDs used to identify the library application.

ReadApplicationContentsAsync

To retrieve a library application as a RAP file, send a GET request for one of the following URLs:

https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/contents
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/contents

The body of the request is empty.

The response will not be human-readable.

UpdateAsync

To update an application, send a PUT request using multi-part form data. The first part should contain the request as JSON content type application/json. The second part should contain the file as binary with content type application/octet-stream:

https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{{packageGUID}}

Note: The alternative version takes a GUID referring to a previously uploaded package, see UploadPackage. The body is empty.

The request includes the following fields:

  • IgnoreVersion - indicates whether or not the version should be validated before updating the library application. By default only upgrades with a higher application version are allowed.
  • RefreshCustomPages - when set to true, the custom pages will be deployed immediately instead of as a task during the application install.
  • FileName - RAP file name of the library application.

DeleteAsync

To delete an application, send a DELETE request. The request URL can take either the application's ArtifactID or the Guid.

https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactId}
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}

The body of this request should be empty.

The body of the response will also be empty. If the delete is successful it will just return a 200 status code.

GetLibraryInstallStatusAsync

To get the most recent library install status of an application, send a GET request to the following URL. The request URL can take either the application's ArtifactID or the Guid.

https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/libraryinstall
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/libraryinstall/{IncludeActions}
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/libraryinstall
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/libraryinstall/{IncludeActions}

The body of this request should be empty.

The response includes the following fields:

  • ApplicationInstallID - the ID of the application installation.
  • ApplicationIdentifier - the identifier of the application.
  • WorkspaceIdentifier - the identifier of the workspace.
  • InstallStatus - the status of the application installation.
  • ValidationResult - if there are any validation failures that require user intervention, the ValidationResult property will hold the options for resolving the failures and retrying the installation.
  • Version - the version of the library application.
  • ValidationMessages - a list of messages associated with the application installation.
  • InstalledBy - the user that initiated the application installation.
  • StartedOn - the start time for the job.
  • CompletedOn - the date and time when the application installation completed.
  • GetCurrentInstallStatus - the action to retrieve the status of the most recent install for the specified application and workspace.

RetryLibraryInstallAsync

To queue or retry an install of an existing application into the Application Library, send a PUT request.

https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/libraryinstall
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/libraryinstall

The body of the request should be empty.

The response includes the following fields:

  • ApplicationIdentifier - the identifier of the application.
  • ApplicationInstallID - the ID of the application installation.
  • InstallStatus - the status of the application installation.

CancelLibraryInstallAsync

To cancel a library install, send a DELETE request with one of the following URLs:

https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/libraryinstall
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/libraryinstall

If the endpoint is invoked with a single application install ID, the JSON request should be empty.

The response includes the following fields:

  • ApplicationIdentifier - the identifier of the application.
  • IsSuccessful - a Boolean value indicating whether the request succeeded or failed.
  • ApplicationInstallID - the ID of the application installation.
  • Message - a string that returns an informative message about the status of the request.

UploadPackageAsync

This endpoint uploads a RAP or XML file to a temporary location in Relativity and returns a unique file identifier along with the meta data for the application. If the file is not in a valid format, a validation exception is thrown. This endpoint is used in conjunction with CreateAsync and UpdateAsync to implement workflows where the application's details need to be displayed for final confirmation before installing the application. To create an application, send a POST request using multi-part form data. The first part should contain the request as JSON content type application/json. The second part should contain the file as binary with content type application/octet-stream:

  https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/package

The body of the request should be empty.

DownloadPackageAsync

This endpoint downloads a RAP or XML file previously uploaded using the UploadPackageAsync endpoint. It takes the unique file identifier as an argument in the URL path and returns a stream of bytes. To create an application, send a GET request with the file's unique identifier in the URL:

  https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/package/{packageIdentifier}/contents

The raw JSON response will not be human-readable.

DeletePackageAsync

This endpoint allows clients to delete an RAP file that has been uploaded to a temporary storage location. To delete a package, send a DELETE request with the package identifier in the URL:

  https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/package/{packageIdentifier}

The body of this request should be empty.

The body of the response will also be empty. If the delete is successful it will just return a 200 status code.