Findsi API documentation
Findsi API documentation
The Findsi API is based around the concepts of Actors, Actions and Targets. Consequently, all logs fed into the system take the shape of “John Doe read Ubik”. In this example “John Doe” is the Actor, “read” is the Action and “Ubik” is the Target.
In order for the log information to be useful to Findsi’s algorithms though, a means is needed to uniquely identify both the Actor and the Target. For this purpose Resources are used. A Resource is an object that globally identifies Actors and Targets. In other words, any API consumer will identify the same thing or person with the same details. Some examples of a Resource might be (Email, john.doe@exampleco.com) and (ISBN, 978-2-0000000-1-9).
Actors can be represented by more than one Resources (at least one). Targets can be represented by only one Resource.
API consumers are not free to use just any kind of Resource. Findsi will only accept Resources it can validate to be well-formed. A constantly evolving list of supported types is available here.
Findsi will never persist Resource details as these details might represent sensitive data. Rather, a Resource object is persisted as a hash. This means that findsi can never send back Resource details to a client. The sole purpose of Resources is internal pattern detection.
Where having global identifiers is useful to Findsi internally, it is less useful to API consumers. Likely, Resource details do not match primary keys in local data stores and they do not allow for sensible filtering of responses. For this reason the concept of Identifiers has been introduced into the API. An Identifier is an object that locally identifies and classifies Actors and Targets.
Both Actors and Targets can be represented by only one Identifier.
Findsi will persist all Identifier details as plain text. This means that Findsi will send back Identifier details to clients, but only to the specific client, that has provided it as part of a log.