Findsi API documentation
Findsi is currently still in beta. As a result the API documentation is subject to change.

logs

Method POST
Rel findsi:logs
Description Allows the client to send a single user activity log to the Findsi API.

Data

The API expects the POST data to be formatted as a JSON object.

Actor

Sending an Actor is required.

  Type Required Description Persisted
Id String Yes Id of the Actor as it is known in the client application. Plain
Classification String Yes Classification of the Actor as it is known in the client application. Plain
Resources Resource[] Yes An array of at least one common Resource that uniquely identifies the Actor Hashed
Resource.Rel String Yes A supported link relation which classifies the Href value. Hashed
Resource.Href String Yes A value that uniquely identifies the Actor. Hashed

Action

Sending an Action is required.

  Type Required Description Persisted
Action String Yes An action is a sting that identifies the actual action performed by the Actor. Hashed

You are free to describe any action in any language you deem fit, as long as you do so consistently.

Target

Sending a Target is required.

  Type Required Description Persisted
Id String Yes Id of the Target as it is known in the client application. Plain
Classification String Yes Classification of the Target as it is known in the client application. Plain
Resource Resource Yes A common Resource that uniquely identifies the Target Hashed
Resource.Rel String Yes A supported link relation which classifies the Href value. Hashed
Resource.Href String Yes A value that uniquely identifies the Target. Hashed

As Findsi learns from user (inter)actions, a log must be in the form: Actor A performed Action B on Target C.

Response

A successful response (HTTP 200) will be an empty HAL document, containing the following:

Besides the default _self and curies links, the following links will be included:

actor The subject of the logged activity
target The object of the logged activity
actor-similars An ordered list of other Actors who are deemed similar to the subject of the logged activity
target-similars An ordered list of Targets that are deemed similar in the context of the subject to the object of the logged activity
target-recommendations An ordered list of Targets that are deemed similar in the context of the subject to the object of the logged activity and that the subject has never interacted with before

Embedded resources

None

Properties

None

Errors

The API may respond with one of the following errors:

401 Unauthorized The Authorization header might be missing or malformed. Alternatively you may have provided an invalid API key.
400 Bad Request Something is wrong with the POST data. Details will be included in the response message.

Example

Supposed we would want to send a log that describes the activity “John read Ubik”. The request could then look like this:

POST /logs HTTP/1.1
Host: api.findsi.com
Accept: application/hal+json
Authorization: findsi_api_key apikey="..."
Content-Type: application/json

{
	"Actor":
	{
		"Id":"12345678",
		"Classification":"User",
		"Resources":[
		{
			"Rel":"email",
			"Href":"john.doe@example.com"
		},
		{
			"Rel":"twitter",
			"Href":"@john_doe"
		}
		]
	},
	"Action":"read",
	"Target":
	{
		"Id":"987654321",
		"Classification":"Book",
		"Resource":
		{
			"Rel":"ISBN",
			"Href":"978-2-0000000-1-9"
		}
	}
}

In this request, the client informs Findsi that user John is known locally as 123456789, that the client classifies it as a User and that John has 2 common Resources that identify him, namely; an e-mail address and a twitter handle. The Action is also clear; John read something. Ubik is apparently identified locally as 987654321 and that same application classifies it as being a book. Globally that particular book is identified by it’s ISBN, being 978-2-0000000-1-9.

The response would the look something like this, depending on what Findsi already knows about John.

Cache-Control no-cache
Content-Length 1094
Content-Type application/hal+json; charset=utf-8
Date Wed, 03 Sep 2014 15:57:52 GMT
Expires -1
Pragma no-cache

{
    "_links": {
        "curies": {
            "href": "http://www.findsi.com/docs/link-relations/{rel}",
            "templated": true,
            "name": "findsi"
        },
        "findsi:actor": {
            "href": "/actors/..."
        },
        "findsi:target": {
            "href": "/targets/..."
        },
        "findsi:actor-similars": {
            "href": "/actors/.../similars"
        },
        "findsi:target-similars": {
            "href": "/targets/.../similars/..."
        },
        "findsi:target-recommendations": {
            "href": "/targets/.../recommendations/..."
        },
        "self": {
            "href": "/logs"
        }
    }
}

Following the links will yield near real-time results, depending on the current load of the API.

 2014 Findsi B.V.    Findsi wesite    Feature backlog    Contact us
   docs/link-relations/logs.md