################# 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 :doc:`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 *********************** Menu ==== List of whole report structure. .. http:get:: /api/menu **Example response**: .. code-block:: json { "id": "gm", "name": "main", "description": "The base group.", "reports": [ "r1", "r2", "r3", "r4", "r5" ], "groups": [ { "id": "g1", "name": "My group 1", "decription": "First API group - for testing." "reports": [ "r6", "r7" ], "groups": [ { "id": "g3", "name": "My group 3", "decription": "Third API group - for testing." "reports": [ "r11", "r12" ], "groups": [] }, ] }, { "id": "g2", "name": "My group 2", "decription": "Second API group - for testing." "reports": [ "r8", "r9", "r10" ], "groups": [ { "id": "g5", "name": "My group 5", "decription": "Fifth API group - for testing." "reports": [ "r22", "r23", "r24" ], "groups": [] } ] } ] } Report Detail ============= .. http:get:: /api/report/ **Example response**: format on first position is used by default!!! .. code-block:: json { "id": "r1", "name": "Report 1", "formats": [ "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 ^^^^^^^ .. http:get:: /api/report/r1/process/?user_id=1 Float ^^^^^ .. http:get:: /api/report/r2/process/?cash=23.55 Char ^^^^ .. http:get:: /api/report/r3/process/?user_name=john Choice ^^^^^^ If parameter is type choice, you choose one from choices. **Parameter specification example**: .. code-block:: json { "parameters": [ { "name": "choicef", "label": "Choice Field Test", "required": true, "type": "select", "choices": [ [ 1, "a" ], [ 2, "b" ], [ 3, "c" ] ] } ] } .. http:get:: /api/report/r4/process/?poll_choice=2 MultipleChoice ^^^^^^^^^^^^^^ If parameter is type choice, you choose one or more from choices. **Parameter specification example**: .. code-block:: json { "parameters": [ { "name": "choicef", "label": "Choice Field Test", "required": true, "type": "select", "choices": [ [ 1, "a" ], [ 2, "b" ], [ 3, "c" ] ] } ] } .. http:get:: /api/report/r5/process/?poll_choices=1;3 Date ^^^^ .. http: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. **_0** etc. **Parameter specification example**: .. code-block:: json { "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**: .. http: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**: .. http:get:: /api/report/r1/process/?date_range_0=this_month Process report ============== .. http:get:: /api/report//process// * **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**: .. http:get:: /api/report/r3/process/json/ This will generate report within default parameters. **Example process report in json**: .. http:get:: /api/report/r3/process/json/?date_range_0=this_month **Example Response**: .. code-block:: json { "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**: .. http: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**: .. http:get:: /api/report/r3/process/csv/?date_range_0=this_month This will return the http response with **Content-Type: text/csv**