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:
Service architecture
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.
Client proxy
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:
- HTTP
- HTTPs
- Net Named Pipes
- NetTCP
RSAPIClient
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:
- APIOptions – provides an instance of APIOptions class associated with this proxy instance. See APIOptions class.
- AuthType – retrieves information about the authentication type used by the proxy to connect to the Services API. It is an AuthenticationType object.
- EndpointUri – indicates the URI for the Services API URI of Relativity.Services running on the IIS. For example, it uses the format "http://localhost/Relativity.Services".
- Repositories – provides access to the group of repositories that support typed data transfer objects.
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.
APIOptions class
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:
- Token – represents an authenticated user. This property is automatically populated with a token value when the user is authenticated so you don’t need to explicitly call a login method. However, if you want to switch to another user, you can call the Login(), LoginWithCredentials(), or TokenLogin() to authenticated the new user.
- WorkspaceID – represents the unique identifier for a workspace in Relativity. A value of -1 indicates the master EDDS database.
-
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.
RSAPIClientSettings class
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
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.
Best practices for proxy creation
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:
- Client methods organized into typed Repositories, such as DocumentRepository, BatchRepository, and others
- Consistent field values based on the type of the Field. In conjunction with DTOs, you can set the StrictMode property on the APIOptions class, which causes the Services API to return consistent Fields for the Read() and Query() methods across all ArtifactTypes.
- ParamArray versions of many List parameters.
- Automatic use of the APIOptions instance held in the RSAPIClient class, so no manual coding is required. See Connect to the Services API.
- Constants for system Artifact and Field names.
- Deep field retrieval on explicit request.
- Casting methods for dynamic Fields.
- Methods for CRUD and query operations on single and multiple artifacts. See Single vs. multiple artifact access pattern.
- Eliminates use of byte array for string values.
This functionality is available in the kCura.Relativity.Client.DTOs and other namespaces.
Single vs. multiple artifact access pattern
Services API DTOs provide standard CRUD methods for single and multiple artifact access.
Single-artifact methods:
- Include CreateSingle(), ReadSingle(), UpdateSingle(), and DeleteSingle().
- Optimized for quick operations and support a single operation per request.
- Success returns an ID for create, a DTO for read, and nothing for update or delete.
- Failure throws an exception.
- Automatically return standard fields.
For more information, see Single-artifact access.
Multi-artifact methods:
- Include Create(), Read(), Update(), and Delete().
- Optimized for performing multiple operations at once and support multiple operations per request.
- Success and failure return a result set including a Success property, a Message, and a list of results (one for each operation).
- Return only the fields specified in the request.
Supported DTOs
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.
| DTO | Supported operations (listed by earliest supported version) |
|||||
|---|---|---|---|---|---|---|
| Create | Read | Update | Delete | Query | Other | |
| Batch | 7.5 | 7.5 | 7.5 | |||
| BatchSet | 7.5 | 7.5 | 7.5 | 7.5 | 7.5 | Cancel - 7.5
Purge - 7.5 |
| Choice | 8.2 | 7.5 | 8.2 | 8.2 | 7.5 | |
| Document | 7.5 | 7.5 | 7.5 | 7.5 | 7.5 | Download native file - 7.5 |
| Error | 7.5 | |||||
| Field | 7.5 | 7.5 | 7.5 | 7.5 | ||
| Folder | 7.5 | 7.5 | 7.5 | 7.5 | ||
| Group | 7.5 | 7.5 | 7.5 | 7.5 | 7.5 | |
| Layout | 7.5 | 7.5 | ||||
| MarkupSet | 7.5 | 7.5 | 7.5 | 7.5 | 7.5 | |
| Matter | 9.1 | 9.1 | 9.1 | 9.1 | 9.1 | |
| ObjectType | 7.5 | 7.5 | 7.5 | 7.5 | 7.5 | |
| RDO | 7.5 | 7.5 | 7.5 | 7.5 | 7.5 | |
| RelativityApplication | 7.5 | 7.5 | 7.5 | |||
| RelativityScript | 7.5 | 7.5 | Execute - 7.5 Retrieve input -7.5 |
|||
| Tab | 7.5 | 7.5 | ||||
| User | 7.5 | 7.5 | 7.5 | 7.5 | 7.5 | |
| View | 7.5 | 7.5 | ||||
| Workspace | 8.2 | 7.5 | 8.2 | 8.2 | 7.5 | |
The operations listed in the previous table are supported at the following levels for DTOs:
- Master database – Workspace, Client, User, and Group
- Master database and Workspace – RelativityScript and Choice
- Workspace – all other ArtifactTypes
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.
