REST API

📘

It is recommended that these new APIs be used in favour of the legacy APIs.

Authentication / Security

The new APIs use the same authentication mechanism as the legacy APIs

Requests to the APIs need to include

• An X-ApiKey header
  • This should have the same value as the Security Key that you entered when configuring the Custom Connector
• An X-Tenant header.
  • Tenant identifier unique to your tenant
• An appid
  • This can be found by going go the edit page for a Custom Connector and taking the id from the URL. E.g. if the url is .../InteractV7/SearchApp/Edit/47 then the appid would be 47

Document APIs

PUT /api/search/connector/{appid}/docs/beginsyncsession

Will set the all documents which have Session deletion mode, to be Session Deletion Candidates. If a document is synchronised through the Add Update endpoint during a synchronisation session, then it will no longer be classed as a Session Deletion Candidate - meaning that it will not be automatically deleted once the sync session is ended.

It is not neccesary to use a synchronisation session if you intend to manage which documents have been pushed or deleted from Interact yourself (as part of your own external tool).

Parameters

No additional parameters.

Response

Http Response: 200.

PUT /api/search/connector/{appid}/docs/addupdate

Used to push documents to Interact. Internally will either add a new document or update an existing document which shares the same GlobalUniqueId

Parameters

Within the request body/content you should provide a serialised collection of documents of the form:

[  
  {  
    "GloballyUniqueId": "string",  
    "DocTypeName": "string", 
    "Title": "string",  
    "Url": "string",   
    "Summary": "string",  
    "AuthorId": "string",  
    "AuthorName": "string",
    "AssetId": "string",  
    "AvatarPath": "string",  
    "CreatedDate": "2024-04-24T21:17:32.535Z",  
    "ModifiedDate": "2024-04-24T21:17:32.535Z",  
    "Taxonomy": [  
      {  
        "Name": "string",  
        "Type": "Text",  
        "TextValue": "string",  
        "NumberValue": 0,  
        "DateValue": "2024-04-24T21:17:32.535Z",  
        "DebuggerDisplay": "string"  
      }  
    ],  
    "CrumbLinks": [  
      {  
        "Key": "string",  
        "Url": "string"  
      }  
    ],  
    "FileContents": "string",
    "Keywords": "string",
    "Bestbets": [
      "string"
    ],  
    "DeletionMode": "Session",  
    "SynchroniseState": "string",  
    "ShouldSaveSynchroniseState": false,  
    "IsPublic": false,
    "ExternalIdentities": [  
      "string"  
    ],  
    "MaterializedPath": "string",    
    "IsParent": true
  }  
]

Response

Http Response: 200

The response content will return information about which GloballyUniqueIds have succeeded (AddedUpdated) or failed (Errors) - including any failure reasons.

{  
  "HasErrors": true,  
  "Errors": [  
    {  
      "HasError": true,  
      "GloballyUniqueId": "string",  
      "Errors": [  
        {  
          "ErrorCode": 0,  
          "ErrorMessage": "string"  
        }  
      ]  
    }  
  ],  
  "AddedUpdated": [  
    "string"  
  ]  
}

Response Error Codes:

PUT /api/search/connector/{appid}/docs/delete

Used to delete the specified documents from Interact

Parameters

Within the request body/content you should provide a serialised collection of document GloballyUniqueIds

[
  "GloballyUniqueId_1",
  "GloballyUniqueId_2",
  "GloballyUniqueId_3"
]

Response

Http Response: 200

PUT /api/search/connector/{appid}/docs/endsyncsession

Used to end a synchronisation session which has been started using the beginsyncsession endpoint.

Deletes any documents which meet the following criteria:

• Already existed before the synchronisation session was started
• Have their Deletion Mode set to Session
• Have not been updated in the current synchronisation session (via the addupdate endpoint)

Parameters

No additional parameters.

Response

Http Response: 200

The response content will include information about how many documents were automatically deleted

{  
  "Deleted": 0  
}

GET /api/search/connector/{appid}/docs/state?docId=X

Gets the state of a document with a supplied globally unique id.

Parameters

The GloballyUniqueId of the document state that you want to get should be included in the request querystring.

Response

Http Response: 200

The response content will include the document state

{  
  "DocExists": true,  
  "DateLastUpdated": "2024-04-24T21:17:32.538Z",  
  "SynchroniseState": "string"  
}

The SynchroniseState is not used internally by the connector framework, and is something that can just be used by your custom connector implementation to record additional meta data or synchronisation state (e.g. a delta token) against a document. I.e. no need to store state in a separate system.

PUT /api/search/connector/{appid}/docs/resetstate?docId=X

Resets the state of a document with a supplied globally unique id.

For the supplied document and its children, this will set the

• DateLastUpdated = null
• DeletionMode = Session
• State = null
• SyncSessionDeletionCandidate = 1

Parameters

The GloballyUniqueId of the document that you want to reset the state for should be included in the request querystring. The state of any children will also be reset.

Response

Http Response: 200

User APIs (External Identities)

The synchronisation framework does not actually add/update/delete any users, and is used to only manage the the External Identities associated with a user.

PUT /api/search/connector/{appid}/users/beginsyncsession

Will set the any user external identities associated with this connector to have their Deletion Mode set to Session, to be Session Deletion Candidates. If a users external identities are updated through the Add Update endpoint, then it will no longer be a Session Deletion Candidate.

Any external identities which have their Deletion Mode set to Session and were not updated during a synchronisation session will automatically be removed when the session ends.

Parameters

No additional parameters.

Response

Http Response: 200

PUT /api/search/connector/{appid}/users/addupdate

Used to push external identities for a user.

Internally will perform a lookup for an Interact user with the matching Email address or Username. If one and only one match is found, then the external identities and other synchronisation state properties (in the context of this connector) are updated.

Parameters

Within the request body/content you should provide a serialised collection of user synchronisation records

[  
  {  
    "Email": "string",  
    "Username": "string",  
    "ModifiedDate": "2024-04-24T21:17:32.542Z",  
    "GloballyUniqueId": "string",  
    "DeletionMode": "Session",  
    "SynchroniseState": "string",  
    "ShouldSaveSynchroniseState": true,  
    "ExternalIdentities": [  
      "string"  
    ]  
  }  
]

Response

Http Response: 200

The response content will return information about which GloballyUniqueIds have been Added, Updated, NotFound or failed (Errors) - including any failure reasons.

{  
  "HasErrors": true,  
  "Errors": [  
    {  
      "HasError": true,  
      "GloballyUniqueId": "string",  
      "Errors": [  
        {  
          "ErrorCode": 0,  
          "ErrorMessage": "string"  
        }  
      ]  
    }  
  ],  
  "Added": [  
    "string"  
  ],  
  "Updated": [  
    "string"  
  ],  
  "NotFound": [  
    "string"  
  ]  
}

Error Codes:

PUT /api/search/connector/{appid}/users/delete

Used to delete a user synchronisation record, including any External Identities (in the context of this connector).

Parameters

Within the request body/content you should provide a serialised collection of document GloballyUniqueIds

[
  "GloballyUniqueId_1",
  "GloballyUniqueId_2",
  "GloballyUniqueId_3"
]

Response

Http Response: 200

PUT /api/search/connector/{appid}/users/endsyncsession

Used to end a synchronisation session which has been started using the beginsyncsession endpoint.

Deletes any user synchronisation records and associated External Identities which meet the following criteria:

• Already existed before the synchronisation session was started
• Have their Deletion Mode set to Session
• Have not been updated in the current synchronisation session (via the addupdate endpoint)

Parameters

No additional parameters.

Response

Http Response: 200

The response content will include information about how many documents were automatically deleted

{  
  "Deleted": 0  
}