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:
GET http://localhost/Relativity.REST/Workspace/1017955/Document/1037184 Host: localhost Authorization: Basic bXkudXNlckBrY3VyYS5jb206Q250VGNoVGhzMTIzNCE= X-CSRF-Header: -
- Request for a collection:
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.
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.
View a JSON response for the retrieval of a single documentPOST
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.
POST http://localhost/Relativity.REST/Workspace/1017955/Document/QueryResult
Host: localhost
Authorization: Basic bXkudXNlckBrY3VyYS5jb206Q250VGNoVGhzMTIzNCE=
X-CSRF-Header: -
Content-Length: 0
Content-Type: application/json
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.
{"condition":" 'Artifact ID' == 1038075" ,"fields":["*"], "relational field":"Group"}
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:
/localhost/Relativity.REST/Workspace/1017955/10JSON representation includes the identifier:
"Artifact Type ID":10
The following examples illustrate a POST request header and body for on a create operation.
- Request header:
POST http://localhost/Relativity.REST/Workspace/1017955/Document Host: localhost Authorization: Basic bXkudXNlckBrY3VyYS5jb206Q250VGNoVGhzMTIzNCE= X-CSRF-Header: - Content-Length: 0
- Request body:
{ "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:
HTTP/1.1 201 OK
Content-Type: application/json
Content-Length: 207
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:
/localhost/Relativity.REST/Workspace/1017955/Document/1046540
The JSON representation for the request must include both the type and identifier. You can also specify the fields you want to update:
{ "Artifact Type Name":"Document", "Artifact ID":1046540, "Control Number":"123lkj" }
The sample code illustrates PUT request header:
PUT http://localhost/Relativity.REST/Workspace/1017955/Document/1046540
Authorization: Basic bXkudXNlckBrY3VyYS5jb206Q250VGNoVGhzMTIzNCE=
X-CSRF-Header: -
Content-Type: application/json
Content-Length: 51
Host: localhost
PUT response
The PUT response contains the status of the update. The following example illustrates the response returned from an update on a Document:
{
"Results": [
{
"StatusCode": 200,
"Success": true,
"Message": "1037184 updated successfully.",
"ArtifactID": 1037184,
"ArtifactGuids": null,
"__Location": "http://localhost/Relativity.REST/Workspace/1017955/Document/1037184"
}
],
"Message": "Update succeeded.",
"ErroredResultCount": 0,
"TotalResultCount": 1
}
DELETE
Use this method to delete resources.
DELETE request
A DELETE request includes only headers. See the following example:
DELETE http://localhost/Relativity.REST/Workspace/1017675/Document/1037053
Authorization: Basic bXkudXNlckBrY3VyYS5jb206Q250VGNoVGhzMTIzNCE=
X-CSRF-Header: -
Content-Type: application/json
Content-Length: 0
Host: localhost
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:
{
"Results": [
{
"StatusCode": 200,
"Success": true,
"Message": "1037053 deleted successfully.",
"ArtifactID": 1037053,
"ArtifactGuids": null,
"__Location": null
}
],
"Message": "Deletion succeeded.",
"ErroredResultCount": 0,
"TotalResultCount": 1
}
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.
