REST API

PerfRepo REST API

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
  • 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
• 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>

• Attachment - TBD
• Metric - TBD

PerfRepo REST Java client

TBD