RSAPI migration strategy

Use the information on this page to learn more about our migration strategy and API usage, as well as about significant differences between the RSAPI and the newer services available as part of the Relativity platform.

Before you continue reading, review the following information:

This page contains the following information:

Migration strategy and API usage

Our recommended migration strategy is based on considering API usage at a feature-to-feature workflow. For example, the Field DTO in the RSAPI is similar to the functionality provided by the Field Manager service. The following sections on this page describe the design differences between the RSAPI and the newer Services APIs surfaces.

You can find a comparison of these APIs in the API migration matrix. See the following related pages for a complete list of both APIs:

Transition from RSAPI repositories to the Services APIs interfaces

Review the differences between these RSAPI repositories and the newer Services APIs interfaces:

  • RSAPI repositories - The RSAPI utilizes one service proxy that distinguishes between objects using the DTOs contained in repositories within the proxy. Each DTO encapsulates the information for the Relativity object that you are manipulating.
  • Services APIs - The newer Services APIs interfaces utilize separate services for each of its surfaces. Relativity objects are distinguished by the contracts passed to the proxy.

The setup for making calls to the proxy is different for RSAPI repositories and the newer Services APIs. For information about how proxies are instantiated, see the following sections:

In the newer Services APIs, separating the APIs into different services means that each is independently versioned and owned. Each service also has its own life cycle.

Contract differences between RSAPI and the Services APIs interfaces

The newer Services APIs interfaces use reference classes to identify objects in Relativity, such as Fields, Object Types, and others. They are described as follows:

  • Each Ref class signifies only one Relativity object.
  • Ref classes are stored in the Relativity.Services.Objects.DataContracts library.

The following table includes Ref classes commonly used in the newer Services APIs:

Ref class name Description
ObjectTypeRef Reference a single object type. You can create ObjectTypeRefs using Artifact Type IDs, GUIDs, or names.
RelativityObjectRef References a specific instance of a Relativity object using Artifact ID or GUID.
ObjectRefValuesPair Associates an object with a list of field values. This class is often used in mass updates to overlay a list of values on an object.
FieldRef References a field by GUID, name, or Artifact ID.
FieldRefValuePair Combines a FieldRef with a value. It's often used in update and create calls to modify the value of a field.

Establish a proxy

RSAPI utilizes a single service proxy that distinguishes between endpoints by repositories. The newer Services APIs utilize a separate proxy for each service.

Use the Object Manager service for CRUDQ operations

The Object Manager service is the primary interface for individual and mass CRUDQ operations on documents and RDOs. It is also the primary interface for querying all objects, not only documents and RDOs. For more information, see the following resources:

Query methods

Querying syntax and structure have undergone major changes from RSAPI to the newer Services APIs, which require you to reference the conditions, sorts and fields in new ways. Additionally, the Object Manager service contains the endpoints previously exposed through the RSAPI for querying objects. We recommend using the Object Manager service for querying on any object type. For a sample query using the Object Manager service, see Sample code for operations on the Object Manager service.

Also, see the following resources:

Mass update methods

The workflows for mass updates have been modified to include these methods:

  • MassUpdateByCriteria() method - updates any objects that meet the specified criteria.
  • MassUpdateByObjectIdentifiers() method - takes a list of objects and updates them with the specified values. Each object is populated with the same values. This endpoint doesn't allow different values per object.
  • MassUpdatePerObject() method - functions similarly to the MassUpdateByObjectIdentifiers() method, except that you can provide different values for each object. By supporting a unique list of values for each object, this endpoint offers finer control over the updates to each field.

For more information and code samples, see Mass update Document objects or RDOs.

Mass create method

The mass create operation has been substantially improved since RSAPI. Migrating to the newer Services APIs involves a significant change in the data contracts and workflows used to interact with them.

The CreateAsync() method takes a list of fields and nested lists of values that are arranged in the same order as the field list. See the following resources:

Sample code for operations on the Object Manager service

The following sample code illustrates how to perform the following operations with the newer Services APIs and the Object Manager service:

  • Create objects from different types of Ref classes.
  • Return a new ServiceFactory object for creating proxies.
  • Perform queries using the QueryAsync() method on the Object Manager service.
  • Create multiple RDOs in a mass operation through the Object Manager service.
  • Create a single RDO through the Object Manager service.

Note: To download a copy of the .CS file with this sample code, click