Create and update resources

The REST API provides you with the ability to use the POST and PUT methods to create and update Relativity objects respectively. It offers the same support for these operations as the Relativity Services API, so that you can create or update Documents, Dynamic Objects, Users, Groups, and other objects. For more information, see Platform APIs and RSAPI reference for REST.

Similar code is used to perform create and update operations. The following code sample illustrates how to call the POST method on a Document. It uses the URL template for a workspace-level resource, and calls the PostAsync() method on an HTTPClient instance, while an update to a Document would use the PutAsync() method. However, POST and PUT have different requirements for the construction of the JSON representations. For more information, see JSON representations for POST and PUT and Document.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
using (HttpClient httpClient = new HttpClient())
{
    // Set up the client.
    httpClient.BaseAddress = new Uri("http://localhost/");

    // Set the required headers.
    httpClient.DefaultRequestHeaders.Add("X-CSRF-Header", "-");
    httpClient.DefaultRequestHeaders.Add("Authorization", "Basic c2FtcGxlYWRtaW5AcmVsYXRpdml0eS5yZXN0OlMwbTNwQHNzdzByZA==");

    // Call the POST method on a Document.
    string url = "Relativity.REST/Workspace/1015349/Document";

    // using Newtonsoft.Json.Linq;
    // for JSON creation
    JObject payload = new JObject
    {
        { "Artifact Type Name", "Document" },
        { "Doc ID Beg", "MOON_001" },
        { "Parent Artifact", new JObject
            {
                { "Artifact ID", 1003697 }
            }
        },
        { "Relativity Native File Location", @"\\share\file.txt" }
    };
    string createInputJSON = payload.ToString();

    StringContent content = new StringContent(createInputJSON, Encoding.UTF8, "application/json");
    HttpResponseMessage response = httpClient.PostAsync(url, content).Result;
    string result = response.Content.ReadAsStringAsync().Result;
    bool success = HttpStatusCode.Created == response.StatusCode;

    // Parse the result.
    JObject resultObject = JObject.Parse(result);
}

JSON representations for POST and PUT

Use these guidelines when constructing JSON representations for create and update operations. They apply to JSON representations used by both POST and PUT methods unless otherwise indicated.

• Use same Artifact Type identifier format in the URL and JSON – You use the same format for the Artifact Type identifier in the URL and the JSON representation. You can use a GUID, an Artifact Type ID, or an Artifact Type Name as the Artifact Type identifier. The JSON may also contain multiple Artifact Type identifiers, but one of them must match that in the URL. For example, if you identify the Artifact Type with a GUID in the URL, then you must include the GUID in the "Artifact Type Guids" property of the JSON representation.
• (Create only) Don’t specify an identifier for an Artifact instance – When you create a new resource (or Artifact instance), don’t include an Artifact ID or GUID in the URL or JSON representation.
• (Create only) Provide a Parent Artifact – When you want to create a resource, you must provide a Parent Artifact in the JSON.

  Note: When the parent object is not a Workspace, you must also include the Artifact Type property (that is the identifier of the parent object type) and set it to the Artifact ID of the parent object. See Create an RDO with a non-Workspace parent object.

• (Create only) When you create a Document, you can add a file to Relativity. The location of the file must be a network path accessible to the Relativity.REST service. Don’t use a local path for this purpose.

  Note: The REST API doesn’t currently support uploading file or updating the data in File fields except during Document creation.

• (Update only) May omit Parent Artifact – The Parent Artifact is not modified during an update operation. Since it is ignored, you can include or omit in the JSON.
• Not all JSON properties passed to Services API – The following JSON properties are not passed as fields to the Services API:
  • Artifact ID
  • Guids
  • Artifact Type ID
  • Artifact Type Name
  • Artifact Type Guids
  • Parent Artifact
  • __Fields
  • __Location
• Don’t include system fields in JSON – When creating or updating a resource, make sure that the JSON representation doesn’t include system fields, such as System Created On, System Last Modified On, or others. Relativity sets these fields. If you attempt to modify them, the Services API rejects your changes by throwing errors.
• Optionally specify fields in an abbreviated format – You have the option to provide only a minimal number of properties when you specify the following fields:
  • Single Object and User fields – The JSON object may contain only an Artifact ID:
    Copy

    1
    {"Artifact ID": 1010101}

  • Single Choice fields – The JSON object may contain only the Artifact ID, and Artifact Type ID or Artifact Type Name as illustrated in these samples:
    Copy

    1
    {"Artifact ID": 1010101, "Artifact Type ID": 7} or {"Artifact ID": 1010101, "Artifact Type Name": "Choice"}

  • Multiple Object fields – These fields are specified as arrays, but you can use the abbreviated format to represent each Single Object.
  • Multiple Choice fields - These fields are specified as arrays, but you can use the abbreviated format to represent each Single Choice.

    For more examples of these formats, see the sample JSON for the PUT method on an RDO.

• (Update only) Specify the update type on multiple value fields – You can specify the update behaviors on these fields:
  • Multiple Choice supports replace or merge behavior.
  • Users field on Group supports add, replace, and remove behavior. See Example: Work with users in groups.

    Note: Multiple Object fields and the Groups field on User do not support update behaviors. Values specified for these field types simply replace the existing ones.

• (Update only) Escape all-numeric field names – When updating a field with the name that consist only of numeric characters, for example, "12147483647," you must escape the name with a tilde (~) character:
  Copy

  1
  2
  3
  4
  5
  6
  
  {
       "Artifact ID": 1038579,
       "Artifact Type Name": "Document",
       "~12147483647":"See text below"
  }

Example: Create a Field

To create a field:

1. Set up your REST client.

   Headers

   • X-CSRF-Header Cross-site request forgery protection header.

     Note: Set the X-CSRF-Header to any value except an empty string. In general, the header value is set to a dash (-). Don't leave this header value blank.

   • Authorization Relativity user name and password in base64 encoding.

   Content-type

   • application/json
2. Perform a POST request against this REST API endpoint:
   Copy

   1
   http(s)://<hostname>/Relativity.REST/Workspace/<workspace artifact ID>/Field

   This sample request payload specifies an optional long text field "Synopsis" not included in search index:

   Copy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   {
     "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
   }

   Success is indicated by the response containing the Artifact ID of the created field:

   Copy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   {
     "Results": [
       {
         "StatusCode": 201,
         "Success": true,
         "Message": "1040773 created successfully.",
         "ArtifactID": 1040773,
         "ArtifactGuids": null,
         "__Location": "http://relativity.domain.com/Relativity.REST/Workspace/1180529/Field/1040773"
       }
     ],
     "Message": "Creation succeeded.",
     "ErroredResultCount": 0,
     "TotalResultCount": 1
   }

   For more information, see Field.

Example: Work with users in groups

The following examples illustrates how you can use the REST API to add, remove, and replace users in groups.

Add a user to a group

To add a user to a group:

1. Set up your REST client.

   Headers

   • X-CSRF-Header Cross-site request forgery protection header.

     Note: Set the X-CSRF-Header to any value except an empty string. In general, the header value is set to a dash (-). Don't leave this header value blank.

   • Authorization Relativity user name and password in base64 encoding.

   Content-type

   • application/json
     
2. Perform a PUT request against this REST API endpoint:
   Copy

   1
   http(s)://<hostname>/Relativity.REST/Relativity/group/<group artifact ID>

   The request payload must specify the group and user Artifact IDs and the operation type of "Add." You can find the group and user Artifact IDs from the Relativity UI or by preforming a query using the REST API. For more information, see Query for resources.

   Copy

   1
   2
   3
   4
   5
   6
   7
   8
   {
       "Artifact ID":  1015028,
       "Artifact Type Name":  "Group",
       "Users": 
       {
        "Add" : [ { "Artifact ID": 1348322, "Artifact Type Name": "User" } ]
       }
   }

   Success is indicated by the following response:

   Copy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   
   {
     "Results": [
       {
         "StatusCode": 200,
         "Success": true,
         "Message": "1015028 updated successfully.",
         "ArtifactID": 1015028,
         "ArtifactGuids": null,
         "__Location": "http://hostname/Relativity.REST/Relativity/group/1015028"
       }
     ],
     "Message": "Update succeeded.",
     "ErroredResultCount": 0,
     "TotalResultCount": 1
   }

Remove a user from a group

To remove a user from a group:

1. Set up your REST client.

   Headers

   • X-CSRF-Header Cross-site request forgery protection header.

     Note: Set the X-CSRF-Header to any value except an empty string. In general, the header value is set to a dash (-). Don't leave this header value blank.

   • Authorization Relativity user name and password in base64 encoding.

   Content-type

   • application/json
     
2. Perform a PUT request against this REST API endpoint:
   Copy

   1
   http(s)://<hostname>/Relativity.REST/Relativity/group/<group artifact ID>

   The request payload must specify the group and user Artifact IDs and the operation type of "Remove."

   Copy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   {
     "Artifact ID": 1015028,
     "Artifact Type Name": "Group",
     "Users": {
       "Remove": [
         {
           "Artifact ID": 1348322,
           "Artifact Type Name": "User"
         }
       ]
     }
   }

   Success is indicated by the following response:

   Copy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   {
     "Results": [
       {
         "StatusCode": 200,
         "Success": true,
         "Message": "1015028 updated successfully.",
         "ArtifactID": 1015028,
         "ArtifactGuids": null,
         "__Location": "http://hostname/Relativity.REST/Relativity/group/1015028"
       }
     ],
     "Message": "Update succeeded.",
     "ErroredResultCount": 0,
     "TotalResultCount": 1
   }

Replace a user in a group

To replace a user from a group:

1. Set up your REST client.

   Headers

   • X-CSRF-Header Blank cross-site request forgery protection header.

     Note: Set the X-CSRF-Header to any value except an empty string. In general, the header value is set to a dash (-). Don't leave this header value blank.

   • Authorization Relativity user name and password in base64 encoding.

   Content-type

   • application/json
     
2. Perform a PUT request against this REST API endpoint:
   Copy

   1
   http(s)://<hostname>/Relativity.REST/Relativity/group/<group artifact ID>

   The request payload must specify the group and user Artifact IDs and the operation type of "Replace."

   Copy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   {
     "Artifact ID": 1015028,
     "Artifact Type Name": "Group",
     "Users": {
       "Replace": [
         {
           "Artifact ID": 13759894,
           "Artifact Type Name": "User"
         },
         {
           "Artifact ID": 13759912,
           "Artifact Type Name": "User"
         }
       ]
     }
   }

   Success is indicated by the following response:

   Copy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   {
     "Results": [
       {
         "StatusCode": 200,
         "Success": true,
         "Message": "1015028 updated successfully.",
         "ArtifactID": 1015028,
         "ArtifactGuids": null,
         "__Location": "http://hostname/Relativity.REST/Relativity/group/1015028"
       }
     ],
     "Message": "Update succeeded.",
     "ErroredResultCount": 0,
     "TotalResultCount": 1
   }