Using okerr API

API Key

To use API get API key from project page (record it somewhere, it’s displayed just once).

To use key with okerrclient, either write it in /etc/okerrclient.conf like this:

api-key = sFeGeFCJPcD9DgcfS6y9OIxPA4D9JXYcl6rwbJlA

or set it in environement:

export OKERR_API_KEY=sFeGeFCJPcD9DgcfS6y9OIxPA4D9JXYcl6rwbJlA

or provide it as okerrclient option --api-key=sFeGeFCJPcD9DgcfS6y9OIxPA4D9JXYcl6rwbJlA. Later in examples we will suppose you have configured project name and textid in /etc/okerrclient.conf.

Basic functions

List indicators

$ okerrclient --api-indicators
$ okerrclient --api-indicators servername:

If optional argument is given, will list only indicators matching prefix.

Show indicator info

okerrclient --api-indicator --name IndicatorName

List by filter

Show indicators which matches all conditions. Condition is either tag (like sslcert or maintenance) or option value (like host=google.com for sslcert type). Use exclamation mark for logical NOT (use quotes in shell for this purpose)

$ okerrclient --api-filter host=google.com sslcert '!maintenance'

Modify indicator (set any properties)

Can set multiple properties at once

$ okerrclient --api-set location=ru retest=1 --name IndicatorName
Changed IndicatorName {'location': 'ru', 'retest': 1}

Useful examples

Set location for all sslcert indicators and retest

#!/bin/sh

for indicator in `okerrclient --api-filter sslcert`
do
	echo set location for $indicator
	okerrclient --api-set location=ru retest=1 --name $indicator
done

Using API directly over HTTP

Okerrclient is recommended way to start working with okerr API, but you may want to use it directly using curl or your own software.

First step is to find proper okerr server which will serve your request:

$ curl https://cp.okerr.com/api/director/mytextid
https://echo.okerr.com/

Here we ask main Control Panel server about server for project with textid mytextid and server points us to server https://echo.okerr.com/. Okerrclient makes this request automatically for any API calls. You may either do this request every time, or store it value and re-use it, projects are moved to other servers rarely (~once per year).

Second step is to perform actual HTTP request to this server. To know request URL, you may use -v option of okerrclient, e.g. okerrclient -v --api-filter whois ERR -i mytextid:

$ okerrclient -v --api-filter whois '!ERR' -i okerr 
getting project url from https://cp.okerr.com/api/director/okerr
status code: 200
getting filtered indicators from url https://echo.okerr.com/api/filter/okerr/whois/!ERR/
...

Now, you can perform this query:

$ export OKERR_API_KEY=LxxUwXRlIBEjwHDn59i6086TXAQ1J2pp06A40auB
$ curl -H "X-API-KEY: $OKERR_API_KEY" 'https://echo.okerr.com/api/filter/mytextid/whois/!ERR/'

Or, you can work without API key, providing user/pass:

$curl --user $OKERR_API_USER:$OKERR_API_PASS 'https://echo.okerr.com/api/filter/okerr/whois/!ERR/'

Reconfigure indicators (check URLs):

$ okerrclient -v -i mytextid --name test --api-set domain=google.com retest=1
getting project url from https://cp.okerr.com/api/director/mytextid
status code: 200
set options for indicator. url https://echo.okerr.com/api/set/mytextid/test
status code: 200
Changed test {'retest': 1, 'domain': 'google.com'}

Copy same method without okerrclient:

curl -H "X-API-KEY: $OKERR_API_KEY" 'https://echo.okerr.com/api/set/mytextid/text' -d 'retest=1&domain=google.com'
Changed test {'retest': 1, 'domain': 'google.com'}