Report Server API

General information

Report Server API is interface to generate reports. Communication is done via HTTPS protocol. Unencrypted connection is available only for testing purposes. SSL is used only to encrypt communication, no client authentication based on SSL certificates is currently available.

Data are transferred in JSON format if not specified otherwise. All reports supports PDF format. Oher data formats such as csv, xls or json, are supported only for some of the reports.

URLs described in this documentation are relative to report-server root URL.

Authentication

Authentication is done via HTTP Authorization header. Depending on configuration, three methods of authentication are available:

HTTP Basic authentication (RFC 2617)

Used for testing and legacy purpose.

Token Authentication

Tokens from GraphQL HORES API are valid for report-server.

Session Authentication

This authentication is appropriate for AJAX clients that are running in the same session context as your website.

Reports API Description

Report Detail

GET /api/report/<report_id>

Example response:

{
    "id": "r1",
    "name": "Report 1",
    "formats": [    # format on first position is used by default!!!
        "json",
        "pdf",
        "csv"
    ],
    "description": "Shows users in date range  given by user.",
    "available_languages": ["cs-cz", "sk-sk", "en-us"],
    "parameters": [
        {
            "name": "choice",
            "label": "Choice Field Test",
            "required": true,
            "type": "select",
            "choices": [
                [
                    1,
                    "a"
                ],
                [
                    2,
                    "b"
                ],
                [
                    3,
                    "c"
                ]
            ]
        },
        {
            "name": "date_range",
            "label": "Date Range",
            "required": false,
            "type": "date_range_select",
            "choices": null
        }
    ]
}

Parameters

Each report detail contains list of parameters. Here is list of possible parameters types with declaration example.

Integer
GET /api/report/r1/process/?user_id=1
Float
GET /api/report/r2/process/?cash=23.55
Char
GET /api/report/r3/process/?user_name=john
Choice

If parameter is type choice, you choose one from choices.

Parameter specification example:

{
    "parameters": [
        {
            "name": "choicef",
            "label": "Choice Field Test",
            "required": true,
            "type": "select",
            "choices": [
                [
                    1,
                    "a"
                ],
                [
                    2,
                    "b"
                ],
                [
                    3,
                    "c"
                ]
            ]
        }
    ]
}
GET /api/report/r4/process/?poll_choice=2
MultipleChoice

If parameter is type choice, you choose one or more from choices.

Parameter specification example:

{
    "parameters": [
        {
            "name": "choicef",
            "label": "Choice Field Test",
            "required": true,
            "type": "select",
            "choices": [
                [
                    1,
                    "a"
                ],
                [
                    2,
                    "b"
                ],
                [
                    3,
                    "c"
                ]
            ]
        }
    ]
}
GET /api/report/r5/process/?poll_choices=1;3
Date
GET /api/report/r6/process/?exit_date=2006-10-25

Date field has 3 input format: * 2006-10-25 * 10/25/2006 * 10/25/06

DateRange

DateRange is specific field. Basically the field consists of 3 subfields.

  1. Char - Predefined date range. You can choose one option from choices and do not specify manually „date from“ and „date to“.

  2. Date - Specify date from.

  3. Date - Specify date to.

Naming of the three subfields consists of parameter name followed by _0 _1 _2. <parameter_name>_0 etc.

Parameter specification example:

{
    "name": "date_range",
    "label": "Date Range",
    "required": false,
    "type": "DateRange",
    "max_lenght": null,
    "choices": [
        [
            "custom",
            "Custom Date"
        ],
        [
            "today",
            "Today"
        ],
        [
            "yesterday",
            "Yesterday"
        ],
        [
            "last_week",
            "Last Week"
        ],
        [
            "last_month",
            "Last Month"
        ],
        [
            "last_year",
            "Last Year"
        ],
        [
            "this_week",
            "This Week"
        ],
        [
            "this_month",
            "This Month"
        ],
        [
            "this_year",
            "This Year"
        ]
    ]
}

Manually define date range example:

GET /api/report/r1/process/?date_range_0=custom&date_range_1=2001-01-01&date_range_2=2036-10-25

Predefined define date range example:

GET /api/report/r1/process/?date_range_0=this_month

Process report

GET /api/report/<report_id>/process/<format>/
  • report_id (string) - report specific id

  • format (string) Optional - specify format in which will report be generated. If not specified, report defualt format will be used (check report-detail endpoint).

Note that optional parameters does not need to be explicitly specified. For example:

Process report witch contains only optional parameters:

GET /api/report/r3/process/json/

This will generate report within default parameters.

Example process report in json:

GET /api/report/r3/process/json/?date_range_0=this_month

Example Response:

{
    "id": "r1",
    "name": "Report 1",
    "description": "Shows users in date range  given by user.",
    "data": [
        [
            "BK",
            "cs_CZ",
            "Benjamin Kittl"
        ],
        [
            "Interface",
            "cs_CZ",
            "Interface"
        ],
        [
            "d",
            "cs_CZ",
            "David Petrů"
        ],
        [
            "q",
            "cs_CZ",
            "Bárta"
        ],
        [
            "hel",
            "cs_CZ",
            "helena"
        ],
        [
            "Karel",
            "cs_CZ",
            "Karl Knödl"
        ],
        [
            "z",
            "cs_CZ",
            "Zuzana"
        ],
        [
            "automat",
            "cs_CZ",
            "Automat"
        ],
        [
            "admin",
            "cs_CZ",
            "Administrator"
        ]
    ]
}

Example process report in pdf:

GET /api/report/r3/process/pdf/?date_range_0=this_month

This will return the http response with Content-Type: application/pdf

Report language selection

Note specific language could be used for export, to do so add HTTP header Accept-Language and choose one of the languages in available_languages. If None or incorrect header given the base system language will be used.

Alternatively you can simply use url parameter „lang“ to specify requested language.

Example process report in csv:

GET /api/report/r3/process/csv/?date_range_0=this_month

This will return the http response with Content-Type: text/csv