Basic REST API concepts

Relativity provides access to many REST endpoints allowing you to easily make API calls from many different coding languages, along with tools such as cURL or Postman. REST calls are made over HTTP, providing language agnostic programming and a high level of flexibility. REST calls operate by providing a URL, an HTTP Method, headers, and in some cases, a body. Once a call is made, you will be returned a status code, headers, and a body.

Tools

Tools like cURL, Postman, or ARC allow for easy testing of REST calls, allowing you to more easily set headers and change a request body. These tools are the quickest way to test REST calls, allowing you to easily see the results of changing your request. In this tutorial, the screenshots provided will be from Postman.

URL

Relativity REST API URLs consist of three parts:

  • The host

    The host is the address of the server where your Relativity instance is hosted. If you go to http://mycompany.com/Relativity to access Relativity through the browser, then your host would be http://mycompany.com.

  • The REST Surface

    • This part of the URL tells the Relativity server to expect a REST request. For our older APIs, this looks like /Relativity.REST/ while our newer Kepler APIs include an additional section: /Relativity.REST/api/

  • The resource

    • The resource tells the Relativity server what specific REST endpoint you are using, and which specific Relativity objects you are working with. In this example, we are telling the server that we want to interact with a document with the Artifact ID 1038579 inside of workspace with the Artifact ID 1015349.

Methods

A core component of REST is providing the server a method that provides instruction for what action you want to perform on the data. With Relativity REST APIs, we currently provide four:

  • GET

    The GET method is used for reading data. In Relativity, GET requests do not contain a body and provide all of the instruction for the server from the URL. We can use GET requests both for data on individual objects, as well as data on types of objects.

    In this example, we are asking the server to provide information on the document with Artifact ID 1038579 inside the Workspace with Artifact ID 1015349.

    In this example, we are asking the server to provide information on all documents inside the Workspace with Artifact ID 1015349.

  • POST

    In Relativity, we use POST methods for two purposes: querying and creating. POST methods are combined with a body to provide information on either the conditions and information on the objects we want to query for, or information on a new object we’d like to create.

    In this example, we are telling the server that we’d like to query for documents inside a workspace with the Artifact ID 1015349, and to expect a body to contain information on which specific documents we’d like returned.

    In this example, we are telling the server that we’d like to create a new document inside a workspace with the Artifact ID 1015349, and to expect a body to contain information about that new document.

  • PUT

    In Relativity, PUT requests are used to update existing data. PUT requests use a body to provide information on what we want the object to look like once it has been updated.

    In this example, we are telling the server that we’d like to update the document with Artifact ID 1038579 in the workspace with Artifact ID 1015349, and to expect a body to contain information on what we’d like that updated document to look like.

  • DELETE

    In Relativity, DELETE requests are used for deleting an object. DELETE requests do not utilize a body, instead providing all the information the server needs to complete the request through the URL.

    In this example, we are telling the server that we’d like to delete the Document with ArtifactID 1038579 in the Workspace with ArtifactID 1015349.

    Note: Not all objects have access to all four of these methods. The documentation on this site details which objects have access to which methods.

Headers

Headers are a way to send extra information along with a REST call without the need for a body. Most Relativity REST API calls require three headers:

  • X-CSRF-Header

    • The cross-site request forgery (CSRF) field must be included in requests and set to blank (empty string) or a single "-". This field provides basic security by preventing malicious parties from scanning your REST endpoint.

    (Click to expand)

  • Authorization

    • The authorization header is required if you are using basic or Active Directory authentication. More information on this header can be found in Authentication.

    (Click to expand)

  • Content-Type

    • The Content-Type header tells the server what format the data provided will be in. For most Relativity REST APIs, Content-Type should be application/json, which means the body will be in JSON format.

Body

Relativity REST bodies are typically only used for POST and PUT methods, formatted in JSON, and the structure can differ depending on the specific API being used. However, while they may be structured differently, there are some themes that typically remain consistent between different APIs.

  • Query

    For queries, Relativity typically allows you to specify a condition, sort order, and fields returned.

    • Condition

      The condition is how you declare which specific objects you want to query for. This condition will be determined by a “condition” property in the JSON body.

    • Sorts

      Sorts are how you determine the order in which the objects are returned. This order will be determined by a “sorts” property in the JSON body.

    • Fields

      Fields determines the fields on the object that are returned from the query. These fields will be determined by a “fields” property in the JSON body. To return all fields, include a “*”.

      This is useful for testing purposes, however, it can dramatically decrease performance. We recommend to only return the fields you need.

    • Create/Update

      For Creates and Updates, you are providing a JSON representation of the object you want to create / update to. The values you set for fields in the JSON will be the entire new object in Relativity once created/updated. To create/update a field, the JSON body will look like this:

      {
	"Artifact Type Name": "Field",
	"Name": "Synopsis",
	"Parent Artifact": {
		"Artifact ID": 1017931
	},
	"Object Type": {
		"Descriptor Artifact Type ID": 10
	},
	"Field Type ID": 4,
	"Is Required": false,
	"Include in Text Index": false,
	"Unicode": true,
	"Allow HTML": true,
	"Open to Associations": true,
	"Allow Sort/Tally": false,
	"Wrapping": true,
	"Linked": true,
	"Allow Group By": true,
	"Allow Pivot": true,
	"Ignore Warnings": true,
	"Available in Viewer": true,
	"Width": 123
}

Authentication

Authentication is handled via the Authorization header. There are currently four ways to authenticate the REST API:

  • Basic authentication

    Basic authentication is when you authenticate with the username and password you use to log in to Relativity. Your username and password must be computed into the Base64 encoding. There are several ways to do this, but in Postman you can type your username and password into the Authorization tab, and it will correctly assign the header value, with the encoded username and password prepended by “Basic”.

    (Click to expand)

    (Click to expand)

  • Cookie authentication

    When a user logs into Relativity, the RelAuth cookie is issued to the browser. This encrypted cookie contains the information that validates the user. This cookie can be passed to the Relativity’s REST APIs instead of an HTTP authorization header. If the encrypted cookie is valid, the call will be authenticated under the credentials of the user who logged in via the web.

    Applications that use custom pages often call Relativity APIs: a typical example can be a custom page that makes AJAX calls to a REST API. The RelAuth cookie is automatically added to any AJAX calls from the browser. This enables most custom page applications to simply make their AJAX calls to the REST APIs and "piggy-back” on top of the browser’s authentication that is automatically handled by Relativity.

    You don't need to include an Authorization header when using cookie authentication from JavaScript within Relativity. The browser performs the authentication.

  • Active Directory authentication

    You can use Active Directory authentication with the REST API by setting AuthenticationData for users through the Relativity UI.

    After configuring AuthenticationData in Relativity, follow the same process for sending credentials as that used by basic authentication.

  • Bearer Token Authentication

    • When using bearer token authentication, clients access the API with an access token issued by the Relativity identity service based on a consumer key and secret obtained through an OAuth2 client. This OAuth 2 client is set up via the UI. In Postman, you can input your access token using the Oauth 2.0 type.

  • (Click to expand)

    • Which will fill the Authorization head allowing you to make the call:

    (Click to expand)

Response

Responses come in two parts, the response code and the response body.

  • Response Code

    • Response codes give you a broad overview of what type of response you’re receiving from the server. For additional information, see HTTP response status codes on the MDN web site.

    Commonly used codes and what they typically mean in Relativity are as follows:

    • 200 OK – Success.

    • 400 Bad Request – Usually an issue with the body.

    • 401 Unauthorized – Usually an authentication issue.

    • 403 Forbidden – Usually a permissions issue.

    • 404 Not Found – Usually an issue with the URL.

    • 500 Internal Server Error – Could be an issue with the body.

  • Response body

    • Response bodies from the REST API will be JSON that differ depending on the type of request. For requests seeking information, such as reads and queries, you will receive the objects and fields requested in a JSON body.

Use Cases

Two common REST tasks are to create a document and to query for an Relativity Dynamic Object (RDO). The examples below provide an endpoint and a code sample.

Create a document

  /Relativity.REST/Workspace/{WorkspaceAppID}/Document

Action: POST

{
	"Artifact Type Name": "Document",
	"Doc ID Beg": "MOON_001",
	"Parent Artifact": {
		"Artifact ID": 1003697
	},
	"Relativity Native File Location": "\\\\share\\file.txt"
}

Query for an RDO

  /Relativity.REST/Workspace/{WorkspaceAppID}/Custom%20Object/QueryResult

Action: POST

{
	"condition":" 'Artifact ID' > 1000000",
	"fields":["*"]
}

Troubleshooting

If your REST call isn't going through correctly, the place to start is usually to identify the response code and see if that gives you a hint of where to look.

A potentially tricky part of working with the REST API can be determining exactly what a request body is supposed to look like. If after checking the Relativity Developer's site, you are still unsure, there are two additional ways you can find this out:

  • The API explorer
  • In Chrome DevTools, you can open up the network tab when you execute an event in the UI. It will capture the REST body that is used for this event, and will give you an example of how to structure yours when you do it programmatically.