Make your first REST call

Use this tutorial to learn about successfully connecting to an API in a RelativityOne instance by making a REST call. By completing this tutorial, you will understand the fundamentals of Relativity's API communication.

Estimated completion time: 30 minutes

See these related pages:

• Basic REST API concepts
• Relativity REST API authentication
• Troubleshoot REST API errors

Before you begin

Before beginning this tutorial, you must have a RelativityOne instance. If you do not have access to a RelativityOne instance, ask your Relativity Administrator to identify an instance that you can use.

After you have a Relativity instance, locate the unique domain identifier for it. This identifier consists of the text between https:// and the following slash (/). In this example, the identifier has the format: xxx.relativity.one.

You also need a tool to make an API call. You can use command-line tools like curl in Linux or Invoke-WebRequest in PowerShell. For first-time Relativity developers, we recommend Postman, which is used for this tutorial. For more information, see the download and installation steps on the Postman web site.

After installing Postman, launch it and create a new request by clicking in the upper-right corner. See the following screen shot:

API authentication

All API calls must authenticate to Relativity. You must send valid user credentials with the API request to process it. If you log in to Relativity with a user ID and password, you can easily use Basic Auth. You must use an alternate method of authentication if you do not use Basic Auth. For available options, see Relativity REST API authentication.

To submit Basic Auth credentials:

1. Use Base64 encoded credentials.
2. Supply them in the HTTP Headers.

You can perform base64 encoding by using a resource, such as the online tool in the Base64 web site, or a programming language of your choice. Combine your credentials into a string separated by a colon (:), and then encode that string. For example, encoding username:password results in this token:

dXNlcm5hbWU6cGFzc3dvcmQ=

In Postman, select the Headers tab. Add the token to the Authorization header, and prefix it with the word Basic:

Make your first REST call to Relativity

In this section, you learn how to connect to Relativity's Ping service. This call accepts an empty payload and responds with a status code of 200.

To make a REST call:

1. Copy and paste the following URI into Postman:
   Copy

   1
   [://example.relativity.one/Relativity.REST/api/Relativity.Services.Environmental.IEnvironmentModule/Ping%20Service/Ping

2. Replace example.relativity.one with your instance domain.
3. Click GET and select POST from the list as the REST verb.
4. Add an X-CSRF-Header and set it to any value for this tutorial, such as a hyphen (-) or CSRF. A CSRF header provides protection against certain vulnerabilities.
5. Verify that your Postman entry matches the following screen shot:



Note: Your Postman entry should use your domain instead of example.relativity.one. It also should use your authorization credentials.

6. Click Send. You should receive a response with a status code of 200 and a body containing OK.

Congratulations! You just submitted your first Relativity API request. All calls to Relativity APIs use the same fundamental steps, so you can use these techniques to interact with any aspect of the Relativity ecosystem. For more information on REST APIs, see RelativityOne APIs.

Troubleshoot a REST call

Use the following information to troubleshoot a failed REST call. For more information, see Troubleshoot REST API errors.

Not authenticated

If you received a message with WWW-Authenticate header set to the value Bearer realm="Relativity.REST", then Relativity did not recognize your credentials:

Verify that you completed the following steps:

• Entered your username and password.
• Set the Authorization header correctly. It should use base64 encoding with the following format: Basic <base64_encoded_credentials>. See API authentication.

Incorrect HTTP Verb

If you receive an HTTP 405 error with a message indicating the API does not support GET, then you used the wrong HTTP verb.

Update the HTTP verb from GET to POST in your request:

404 Not Found

If you receive a 404 Not Found response, make sure that the URI is connecting to the correct API endpoint. The endpoint should look like the following example, except that your instance domain should replace example.relativity.one:

1
[://example.relativity.one/Relativity.REST/api/Relativity.Services.Environmental.IEnvironmentModule/Ping%20Service/Ping

If your endpoint is correct, verify that you entered a non-empty string as the value of the X-CSRF-Header: