Supported HTTP methods

The Relativity REST API supports common HTTP methods, including GET, POST, PUT, and DELETE.

GET

Use this method to retrieve resources, such as a single workspace. You can use GET to retrieve a collection of resources, but it doesn't support the use of filtering. For this reason, we recommend performing queries with the POST method, which supports search conditions. The REST API uses the object type to determine the default set of properties returned on a collection. See Default properties by resource type.

GET request

A GET request includes headers and supports a few query string parameters. See Retrieve resources.

• Request for a single resource:

  1 2 3 4

  GET http://localhost/Relativity.REST/Workspace/1017955/Document/1037184 Host: localhost Authorization: Basic bXkudXNlckBrY3VyYS5jb206Q250VGNoVGhzMTIzNCE= X-CSRF-Header: -

• Request for a collection:

  1 2 3 4

  GET http://localhost/Relativity.REST/Workspace/1017955/Document Host: localhost Authorization: Basic bXkudXNlckBrY3VyYS5jb206Q250VGNoVGhzMTIzNCE= X-CSRF-Header: -

• Request specifying fields with the ?Fields modifier. See Retrieve specific Fields on objects.

  1 2 3 4

  GET http://localhost/Relativity.REST/Workspace/1017955/Document?Fields=Extracted%20Text Host: localhost Authorization: Basic bXkudXNlckBrY3VyYS5jb206Q250VGNoVGhzMTIzNCE= X-CSRF-Header: -

GET response

A GET response includes a JSON representation of the resource at the requested URL in the body. The response JSON for a single request includes many more fields than that for a collection. The collection response looks similar to a query response.

POST

Use this method for querying and creating resources as well as retrieving data.

POST requests for queries

You don't need to provide a request body when you use POST to query for objects. In fact, a query operation is similar to using the GET method to retrieve a collection. It returns the default fields in the JSON response. See Query for resources and Default properties by resource type.

The request header for a query includes the Content-Type field as well as the CSRF and Authorization fields. See HTTP headers.

While not required, you can use a body for a query when you want to request specific fields or use conditions. For object types that support paging, you can also specify a page size in the header. See Syntax for query conditions and Paging.

POST requests for create operations

When you use POST to create a resource, you must specify the fields in a valid JSON representation. The body for create request must include the Parent Artifact. In addition, you must supply an Artifact Type Name, Artifact Type ID, or GUID in the JSON representation that matches the identifiers provided in the URL. See Create and update resources.

The following examples illustrate how to use these type identifiers in the URL and JSON representations.

• URL specifies the type by GUID:

  /localhost/Relativity.REST/Workspace/1017955/4c639ae4-665d-4034-8126-c0680fd47d60

  JSON representation includes the "Artifact Type Guids" entry and an identifier:

  <p>"Artifact Type Guids":["4c639ae4-665d-4034-8126-c0680fd47d60"]

• URL specifies the Artifact Type Name as Document:

  /localhost/Relativity.REST/Workspace/1017955/Document

  JSON representation includes the type name:

  "Artifact Type Name":”Document”

• URL specifies Artifact Type ID as 10:

  1	/localhost/Relativity.REST/Workspace/1017955/10

  JSON representation includes the identifier:

  1	"Artifact Type ID":10

The following examples illustrate a POST request header and body for on a create operation.

• Request header:

  1 2 3 4 5

  POST http://localhost/Relativity.REST/Workspace/1017955/Document Host: localhost Authorization: Basic bXkudXNlckBrY3VyYS5jb206Q250VGNoVGhzMTIzNCE= X-CSRF-Header: - Content-Length: 0

• Request body:

  1 2 3 4 5 6

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

POST response

When you use POST to run a query, the response includes a collection of resources with a set of default fields returned for the object type. When you create a single object, the response body contains its JSON representation. When you create multiple objects, the response body contains an array of URLs. See Query for resources and Create and update resources.

See the following example of a response header:

PUT

Use this method to update resources.

PUT request

When updating a resource, you must supply an Artifact Type Name, Artifact Type ID, or GUID in the JSON representation that matches the identifiers provided in the URL. See Create and update resources.

For example, the following URL contains Document as the Artifact Type Name and 1046540 as the identifier for a PUT request:

The JSON representation for the request must include both the type and identifier. You can also specify the fields you want to update:

The sample code illustrates PUT request header:

PUT response

The PUT response contains the status of the update. The following example illustrates the response returned from an update on a Document:

DELETE

Use this method to delete resources.

DELETE request

A DELETE request includes only headers. See the following example:

DELETE response

A DELETE response returns the status of the operation. When the delete operation succeeds, the response includes the ArtifactID of the object removed from the system. See the following example:

Escaping special characters

Use an encoding algorithm to escape special characters that appear in Relativity field names and other strings sent to the REST layer. You need to escape special characters that appear in the body of a request as well as those in query string parameters of a URL.