REST API

PerfRepo REST API

This artices describes raw REST API, for more convenient usage you can use PerfRepo Java client which is described on PerfRepo Java client Wiki page.

For purposes of automatization, PerfRepo comes with very simple REST API. This document should give you all necessary information for using it. First comes description of REST API URLs and it's object structure, second part describes usage of PerfRepo REST Java client, so Java users can jump straight to that and don't have to bother themselves with pure XML endpoints.

URL's

Here comes a list of all REST URL's available in PerfRepo.

• Test and metric related methods
  • GET /rest/test/uid/{testId} - get test with all subobjects (by it's UID)
  • GET /rest/test/id/{testId} - get test with all subobjects
  • POST /rest/test/create - create a new test
  • POST /rest/test/id/{testId}/addMetric - add new metric to an existing test
  • DELETE /rest/test/id/{testId} - delete test and all subobjects
  • GET /rest/metric/{metricId} - get metric
• Test execution related methods
  • GET /rest/testExecution/{testExecutionId} - get test execution with all subobjects
  • POST /rest/testExecution/create - create a new test execution
  • POST /rest/testExecution/update/{testExecutionId} - update existing test execution
  • DELETE /rest/testExecution/{testExecutionId} - delete test execution and all subobjects
  • POST /rest/testExecution/addValue - add value to existing test execution
  • GET /rest/testExecution/attachment/{attachmentId} - get attachment
  • POST /rest/testExecution/{testExecutionId}/addAttachment - add new attachment to an existing test execution
  • POST /rest/testExecution/search - search for test executions
• Reports related methods
  • GET /rest/report/id/{reportId} - get report with all properties
  • POST /rest/report/create - create a new report
  • DELETE /rest/report/id/{reportId} - delete report and its properties
  • POST /rest/report/id/{reportId}/addPermission - add permission to report
  • POST /rest/report/id/{reportId}/updatePermsission - update permission of report
  • POST /rest/report/id/{reportId}/deletePermission - delete permission from report. You have to post the permission entity that you want to delete.
• Info methods
  • GET /rest/info/version - returns plain text version of PerfRepo deployed on server
• Returned HTTP statuses
  • GET methods, on success, return HTTP STATUS 200 (OK) with requested entity
  • POST methods, on success, return HTTP STATUS 201 (Created) with properly set Location header, returned entity contains id of newly created object
  • DELETE methods, on success, return HTTP STATUS 204 (No content)

Autentication

Note that all REST URL's are secured by Basic HTTP autentication. Hence, you must provide HTTP headers with login and password according to the Basic HTTP standard. As a best practise is considered to create a separate user for REST operations. In future releases, there is plan to differ "robots" and "live users".

Structure of entities

Communication between client and server is done via XML, so we need to know the format of the messages. PerfRepo uses RestEasy for automatic serialization of entities into the XML format, so for better understanding see the documentation for RestEasy and entity classes. Here are examples of serialized entities.

• Test - test is usually already present in PerfRepo, so there is no need to create it via REST, but sometimes it's convenient to retrieve the test by UID or ID. The format of Test entity in XML is following:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<test groupId="perfrepouser" name="testName" uid="testUid">
    <description>Description of the test</description>
    <metrics>
        <metric comparator="LB" name="metric1">
            <description>this is a test metric 1</description>
        </metric>
        <metric comparator="HB" name="metric2">
            <description>this is a test metric 2</description>
        </metric>
        <metric comparator="HB" name="multimetric">
            <description>this is a metric with multiple values</description>
        </metric>
    </metrics>
</test>

• TestExecution - usually the most important entity in PerfRepo representing one test build/run.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<testExecution name="execution1" started="2015-03-16T14:05:27.729+01:00" testId="1"><!-- testId is the ID of the test that this execution belongs to -->
    <parameters><!-- TestExecution parameters -->
        <parameter name="param1" value="value1"/>
        <parameter name="param2" value="value2"/>
    </parameters>
    <tags>
        <tag name="tag1"/>
        <tag name="tag2"/>
    </tags>
    <values><!-- List of values that this test execution consist of on per metric basis. -->
        <value metricName="metric1" result="12.0"/>
        <value metricName="metric2" result="8.0"/>
    </values>
</testExecution>

• Test execution search criteria entity - in order to search test executions via REST using the /rest/testExecution/search URL, you need to post the criteria object, which has following format (every element is optional, so you can combine it to create complex search criteria):

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<test-execution-search>
    <ids> <!-- IDs of the test executions to retrieve several exactly known test executions -->
        <id>4739</id>
        <id>4740</id>
    </ids>
    <executed-after>YYYY-MM-DD HH:ss</executed-after> <!-- filtering by execution timestamp -->
    <executed-before>YYYY-MM-DD HH:ss</executed-before>
    <test-uid>test-uid</test-uid> <!-- filter by assigned test UID -->
    <test-name>testName</test-name> <!-- filter by assigned test name -->
    <tags>tag1 tag2</tags> <!-- space separated list of tags -->
    <parameters>
        <parameter> <!-- filtering by test execution parameters -->          
            <name>param1</name>
            <value>value1</value>
        </parameter>
    </parameters>
    <limit-from>0</limit-from> <!-- index of the test execution in the list to be started from, used for pagination -->
    <how-many>10</how-many> <!-- limit number of test executions retrieved -->
    <group-filter>MY_GROUPS</group-filter> <!-- filter by groups that the test is assigned to, possible values MY_GROUPS, ALL_GROUPS -->
    <order-by>DATE_ASC</order-by> <!-- ordering of the result -->    
</test-execution-search>

• Attachment - TBD
• Metric - TBD
• Report - at the first sign, the structure of properties has extra entry tag and the key is repeated twice. This is done because they're internally stored as Map for easier manipulation. Also note the user attribute, because every report is assigned to specific user. Allowed options for type are (so far) Metric and TestGroupReport.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<report name="report" type="TestReport" user="perfrepouser">
    <properties>
        <entry>
            <key>key</key>
            <value name="key" value="value"/>
        </entry>
    </properties>
</report>

• Permission - for adding permissions to reports. The dependence of elements is following. If access-level is GROUP, then group-id must be specified. If access-level is USER, than user-id must be specified. If access-level is PUBLIC, none of user-id or group-id is relevant. With access-level public, the report is available even without logging in.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<report-permission>
    <access-type>READ</access-type> <!-- possible values: READ, WRITE -->
    <group-id>1</group-id> <!-- must be specified if access-level == GROUP -->
    <access-level>PUBLIC</access-level> <!-- possible values: USER, GROUP, PUBLIC -->
    <report-id>25</report-id> <!-- always mandatory -->
    <user-id>7</user-id>  <!-- must be specified if access-level == USER -->
</report-permission>