Open topic with navigation
The Services API enables you to write highly customized solutions on top of Relativity. It provides the functionality to perform development tasks such as creating Relativity objects using DTOs, performing mass operations on a group of Relativity objects in a single call, creating Dynamic Objects for use in Relativity, and integrating Relativity with external applications to extract, update, or add data.
This page contains the following information:
See these related pages:
The RelativityServices API is a web service based on Windows Communication Foundation (WCF), and it is hosted on IIS. The Services API has its own virtual directory and runs in its own application pool. In addition, it can be installed with the WebAPI as part of the Relativity web server component.
The Services API is installed on the Relativity web server as an additional IIS application, called Relativity.Services. Most of the configuration of Relativity.Services is determined by the settings in the web.config file of the Relativity.Services virtual directory. Some configuration options are also controlled through the Instance setting table of the EDDS database.
In addition, a local version of the Services API runs on every agent server in your environment. This service uses the same code and database connection as your other Services API servers. However, the Services API on the agent server is self-hosted inside the agent Windows service, so you don't need to install any IIS infrastructure on the servers. Since only the agents on these servers use the Services API, the service only listens on the loopback interface using a named pipe and TCP port 6867. No firewall changes or other configuration should be required in most cases.
Note: If your environment already uses the TCP port 6867 for other software, you can update value for the port number in the ServicesAPIMetadataPortOnAgentServers
setting in the Instance setting table on the EDDS database.
For more information on changing the default Services API configuration, see Configuration options.
To connect to the Services API, you must instantiate a proxy. In the Services API, the client-side proxy enables applications to send and receive messages over a variety of transport protocols. This proxy is created by instantiating the RSAPIClient class in the kCura.Relativity.client.dll. To use the Services API for custom development, you need to write .NET code and reference this assembly in your project. You also have to configure endpoints that this proxy uses to communicate with the Services API. When you call an operation on the RSAPIClient, your request is sent to the Services API.
The Services API supports the following transport protocols:
The RSAPIClient class exposes all of the available Services API functionality by connecting to the Authentication, DataManipulation, SetExecutor, and FileTransfer services. You can instantiate this class to create a proxy that includes methods used to interact with DTOs and other artifacts.
The RSAPIClient class has the following properties:
This class includes a comprehensive set of methods, which you can use to log in, create Artifact requests, query for Artifacts, and perform other tasks.
The APIOptions class controls who makes a call for any given method, where this user is making the call to, and how that call behaves. The members of this class include the following properties:
StrictMode – determines the convention used when returning or supplying fields to the Create(), Read(), Update(), Delete(), and Query() methods. When this field is True, a subset of fields (using consistent names and datatypes) are available across the various methods. Strict mode is enabled by default for the Services API DTOs.
You can programmatically set client-side configuration by passing an RSAPIClientSettings object to the overloaded constructor for the RSAPIClient class. This RSAPIClientSettings class can be used to define the CertificateFindValue and the CertificateValidation settings. See Configure the Services API.
RSAPIClientServiceOperationFailed event is raised when the RSAPIClient throws an exception due to a failure or operation error. See RSAPIClientServiceOperationFailed event in the Services API class libraries.
For information about programmatically establishing a client proxy from Relativity event handlers, agents, and custom pages, as well as
from a standalone application, see Connect to the Services API.
The Services API now includes Data Transfer Objects (DTOs) that simplify coding and minimize errors by providing typed wrappers for system Artifacts and Fields.
DTOs provide the following features as well as offering typed wrappers for system Artifacts and Fields:
This functionality is available in the kCura.Relativity.Client.DTOs and other namespaces.
Services API DTOs provide standard CRUD methods for single and multiple artifact access.
For more information, see Single-artifact access.
You can use the following table to locate code samples for DTOs. The table lists the Relativity version when the support for a specific operation was first introduced. Click the version number under an operation to display a code sample for it.
(listed by earliest supported version)
|BatchSet||7.5||7.5||7.5||7.5||7.5||Cancel - 7.5
Purge - 7.5
|Document||7.5||7.5||7.5||7.5||7.5||Download native file - 7.5|
|RelativityScript||7.5||7.5||Execute - 7.5
Retrieve input -7.5
The operations listed in the previous table are supported at the following levels for DTOs:
Note: For Error, the Create() method is supported at the master database and Workspace levels. However, all Errors are written to the master database, and the Workspace where the Error occurred is inferred from the WorkspaceID value set in the APIOptions instance.
For complete operations reference and code samples, see RSAPI reference for .NET.