Getting started

In order to communicate with the Findsi API a key is required. To apply for an API key, please contact us. Once you receive your key, be sure to keep it safe and secret. API keys are unique and are used to identify you as an authenticated API consumer. Your key is associated with all of your logge data and as such cannot be changed. Issuing a new key is possible, but will inevitable lead to dat loss.

In communicating with the API, you always send your API key along with a request in the Authorization header, like so:

GET HTTP/1.1
Host: api.findsi.com
Accept: application/hal+json
Authorization: findsi_api_key apikey="..."

Note that, instead of using application/json as the accepted media-type, application/hal+json is used.

If all went well the returned response looks something like this (formatted for readability):

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

{
    "_links": {
        "curies": {
            "href": "http://www.findsi.com/docs/link-relations/{rel}",
            "templated": true,
            "name": "findsi"
        },
        "findsi:logs": {
            "href": "/logs"
        },
        "findsi:actors": {
            "href": "/actors{?filter,page_index}",
            "templated": true
        },
        "findsi:targets": {
            "href": "/targets{?filter,page_index}",
            "templated": true
        },
        "findsi:shortcuts": {
            "href": "/shortcuts"
        },
        "self": {
            "href": "/"
        }
    }
}

From here on, you simple follow one of the returned links to get to the desired resource(s). What each link leads to is indicated by it’s link relation. How such a resource should be accessed (GET or POST) is detailed in the section Link Relations.