Skip to content

Rest and Json

The Syncer allows you to directly import Json Files or Simple Rest APIs, which return plain Json and don't have special Authentication.

Rest API

Everything is configured using an Account. The Following Options are available:

Option Description
auth_type Empty if you want a Header based auth, else Basic or Digest
cert Path to a Certificate for Certificat Based auth
request_headers Send Custom Headers like for Auth or Content Type
data_key Empty or key where the Data will be found.
hostname_field In which field can the Hostname be found
rewrite_hostname Jinja if you want to rewrite the hostname
method The request can be changed from GET to POST.
post_body If POST mode, specify the JSON Body here, Jinja is supported
page_limit Records per request, reads the API page by page. Empty reads everything at once
page_offset_field Name of the API parameter for the records to skip, default offset
page_limit_field Name of the API parameter for the records per page, default limit
filter_field Field of a record that is checked against filter_lookup_table
filter_lookup_table Lookup Table whose first column lists the values to import

POST Body with Jinja

Since 4.5

post_body is rendered with Jinja before the request is sent. All Jinja functions work there, including {{ACCOUNT:name:field}}, secret_value() and the Lookup Tables. There are no host attributes, the body is built once per import.

To send one entry per line of a lookup table, loop over lookup_rows(). Use the tojson filter for the values, it adds the quotes and escapes whatever would break the JSON:

{"filter": [{% for row in lookup_rows('sites') %}{"name": {{ row.location | tojson }}, "dc": {{ row.datacenter | tojson }}}{% if not loop.last %},{% endif %}{% endfor %}]}

If the columns of the table already match the fields the API expects, the whole table can be sent as a list:

{"items": {{ lookup_rows('sites') | tojson }}}

An undefined variable or a syntax error stops the import with an error instead of sending a broken body.

Paging

Since 4.5

An API that returns too many records for one answer can be read page by page. Set page_limit to the number of records per request, it is sent as the value of page_limit_field. The Syncer then asks with an offset of 0, then with page_limit, then with twice page_limit and so on, until a page brings fewer records than page_limit.

page_offset_field and page_limit_field name the parameters the API expects for the records to skip and the records per page. With GET they are sent as URL parameters, with POST they are added to the top level of post_body, which then has to be a JSON object. For page_limit 500 and the default field names, the second request of a POST sends:

{"conditions": [], "offset": 500, "limit": 500}

If the API ignores these parameters and keeps sending the same records, the import stops with an error instead of asking forever.

Filter with a Lookup Table

Since 4.5

Some APIs can't filter for a long list of values. Then read everything and let the Syncer filter: filter_field names the field of a record, filter_lookup_table a Lookup Table. Only records whose value of that field is in the first column of the table are imported, all others are skipped. The table may use the mode Table with just one column:

service
Web Shop
Mail

The values have to be written exactly as the API delivers them. A record without the field is skipped. If the table does not exist, the import stops with an error, so it never imports nothing by accident.

The filter applies to the import and to the inventory, and also to JSON files.

JSON File

Like for Rest API, everthing is configured in an Account. Here, you just need to set the Path to the File. Fields like hostname_field are described above in the description of Rest API

When Using the data_key

The data_key can be confusing. Here two examples to see what it's for.

In this Example, data_key needs to be 'results'

{'results': [{data},{data}]}

In this case, the data key needs to be empty

[{data},{data}]