API Explorer

The API Explorer is an interactive application used for making calls to Kepler service endpoints directly in Relativity. It includes modules used to perform CRUDQ operations on a Relativity resource. Each module contains the URLs for service endpoints, the ability to view fields used in the payload request, and information about fields returned in a response.

The API Explorer consumes an OpenAPI file generated using Open API 3.0 specification, which is a common standard for REST APIs. After you install the API Explorer, it searches for an OpenAPI file in each application RAP file installed in your Relativity instance. It then reads the file and populates a web interface, so that you can interact with the APIs supported by that specific application. For more information, see What Is OpenAPI? on the Swagger website.

This page contains the following information:

• Before you begin
• Quickstart steps
• API Explorer tutorial

Before you begin

Complete the following tasks to set up the API Explorer:

• Obtain access to an instance of Relativity used for development purposes.
• Download the RAP file for the API Explorer from the Relativity App Hub.
• Install the RAP file for API Explorer in a workspace. For more information, see Installing applications on the Relativity Documentation site.

Quickstart steps

The quickstart steps include high-level information about how to navigate through the API Explorer and make REST calls. You may want to use these instructions if you are already familiar with using OpenAPI documentation. For additional information about available services and requirements for making REST calls, see Relativity services in REST.

If you would like detailed navigation instructions and conceptual information, see the API Explorer tutorial.

1. Navigate to the API Explorer in the workspace where you installed it.
2. In the left navigation pane, click on an application associated with the API that you want to use.
3. Click on the version of the API that you want to use. The API Explorer displays a list of available endpoints with their HTTP methods and URLs.

   (Click to expand)

   

4. To view the header parameters, and the request body, click on an endpoint.
5. Click Try it out to set values for the header parameters and the fields in the request body.

   (Click to expand)

   

6. Enter values for the parameters and fields and then click Execute to make a REST call.

   Note: If you execute a REST call, your instance database may be modified. You can change, delete, or corrupt data using the API Explorer interface.

7. Review the response. For more information, see View the response.

   (Click to expand)

   

API Explorer tutorial

The API Explorer tutorial provides detailed information for each step used in the process for inspecting a REST API. It uses the Object Manager service to step through the features of the API Explorer, while also explaining key concepts underlying REST calls. For example, it describes the parameters and fields that you need set for a specific endpoint on the Object Manager service. If you need only minimal instructions for navigating in the API Explorer, see Quickstart steps.

This tutorial includes the following sections:

• Select an API to inspect
• View the parameters and request body
• Set the parameters for the HTTP header
• Set the fields in the request body
• Set the parameters for the HTTP header
• View the response

Select an API to inspect

In the API Explorer, you can interact with an API by selecting it, and then choosing the version that you want to use for REST calls. Complete the following steps to select the API and its respective version:

1. Navigate to the API Explorer in the workspace where you installed it.

   The left navigation pane lists applications that have OpenAPI files describing the API for an application.

2. In the left navigation pane, click on an application. For example, click Relativity.ObjectManager.

   The center pane displays the available versions of the API used for the application. In this example, the center pane displays the available versions of the Object Manager API.

   (Click to expand)

   

3. Click on the version of the API that you want to use.

   The center pane now displays a list of available endpoints that you can use to make REST calls for this versioned service. The HTTP method and route for each endpoint is displayed. This example uses Object Manager v1, but you can easily switch to Object Manager v2.

   (Click to expand)

   

View the parameters and request body

A REST request includes header information, and may include key-value pairs in a JSON payload in the body. To view the header parameters and the request body, click on an endpoint. For example, click on the read endpoint for the Object Manager API as shown in the following screen shot:

(Click to expand)

The request page contains the following information:

• HTTP method and URL or route - In the Object Manager service, the read operation is executed by making a POST request to the following URL or route:

  

• Parameters - variables in the URL or route. For more information, see Describing Parameters on the Swagger website.

  (Click to expand)

  

  Object Manager API example

  The read endpoint on the Object Manager service requires these parameters:

  • workspaceID - the Artifact ID of a Relativity workspace.
  • XCSRF-Header - a security or authorization token.
• Request body - contains the fields required for a specific endpoint. For more information, see Describing Request Body on the Swagger website.

  The Request body section contains the following tabs:

  • Example Value tab - displays the values for the fields in the request body.
  • Model tab - displays different parts of the request body for a specific endpoint.

    (Click to expand)

    

    Object Manager API example

    In the Object Manager service, a read endpoint requires the following fields displayed on the Example Value and Model tabs:

    • ArtifactID - the identifier for the object that you want to read.
    • Guid - an optional identifier for the object. This property is nullable, indicating it isn't required for the operation.
    • Fields - a JSON array containing the fields on the RelativityObject instance that you want to read. Each field property should be an element in the array.

    For more information about field values, see Object Manager service.

Set the parameters for the HTTP header

Before making a REST call, you must set the values for the required parameters and fields in the request body. Click Try it out to set the values that you want to use.

(Click to expand)

The Parameters section now displays a form listing the required values that you need to add. For the read endpoint on the Object Manager service, enter the following value in this form:

• workspaceID - an integer value representing the Artifact ID of the workspace containing the object that you want to read. For this example, the Artifact ID is 1017095.

(Click to expand)

Set the fields in the request body

To set the fields in the request body, scroll to the Request body section of the form. For the read endpoint on the Object Manager service, enter the following field values:

• ArtifactID - the identifier for the object that you want to read. This example reads a RelativityObject called Foo, which has the ArtifactID of 1039608.
• Guid -an optional identifier for the object. This property is nullable, indicating it isn't required for the operation. Leave this field blank or remove it from the request body.
• Fields - a JSON array containing the fields on the RelativityObject instance that you want to read. For this example, the object contains only the Name and Description fields, which this operation will read.

(Click to expand)

For more information about field values, see Object Manager service.

Make the REST call

After you have set the parameters and field values, you are ready to make a request to the service. Click Execute.

Note: If you execute a REST call, your instance database may be modified. You can change, delete, or corrupt data using the API Explorer interface.

View the response

A response is returned after a REST call finishes executing. It includes a status code indicating whether the call was successful, HTTP headers with general information about the response, and possibly a response body with any requested data. For more information, see Describing Responses on the Swagger website.

Review the following response:

(Click to expand)

In the API Explorer, the Responses section includes the following subsections:

• Curl - a representation of your original request formatted as a Curl command.
• Request URL - the URL that was used to make the request.
• Server response section - includes the following information:
  • Code - the status code for the request. Status codes of 200 indicate a successful request. For more information, see HTTP status codes.

  • Response body - the content returned by the service, which contains is key-value pairs formatted as JSON.

    Object Manager API example

    For the Object Manager service, the response body includes the following fields:

    • ParentObject - the parent object of the Foo object included in the request. This field contains the Artifact ID of the parent object.
    • Name - the name of the object that was specified in the read request. It was the name FooTwee.
    • FieldValues - an array of objects containing information about the fields specified in the request. The following properties for the fields are returned:
      • Name - it has the Name property set to Name, while the ArtifactID is 1039339, and the FieldType is Fixed Length Text.
      • Description - it has the Name property set to Description, while the ArtifactID is 1039404, and the Value is Updated 2:30 on 7/22.
    • ObjectType - include the ArtifactID and other information.
  • Response headers - a group of key-value pairs that provide additional information about the data returned in the request, such as supported version of the API, the content type returned, and others. For more information, see HTTP headers.
• Responses section - includes the following information:
  • Code - the status code for the request.
  • Description - a description of the status code, if available.
  • Links - links to other related API calls, if applicable.