ApiaryReportingApi.apib

FORMAT: 1A
HOST: http://api.apiary.io/

# Apiary Dredd tests reporting API

## Group Test Runs

### Test Run collection [/apis/{suite}/tests/runs]

- Parameters
    - suite: jakubtest (string, required) - API suite domain identificator

- Attributes
    - _id: `507f1f77bcf86cd799439011` (string, optional) - Unique object id. DO NOT USE IT WHEN CREATING! Used in post body only for purpose of testing this blueprint.
    - endpoint: `http://localhost:3000` (string, required) - protocol with hostname and optional PORT in URL format, root for all transactions in this Test Run
    - reportUrl: `https://absolutely.fancy.url/wich-can-change/some/id` (string, required) - Report UI URL
    - blueprints (array, required) - Array of blueprints used for the test run
        - (object)
            - filename (string, required) - file name
            - raw (string, required) - raw blueprint content in Markdown
            - annotations (array, required) - Array of annotations (errors and warnings) which occurred during parsing or testing
                - (object)
                    - type (enum[string]) - Type of the annotation.
                        - `error`
                        - `warning`
                    - component (enum[string]) - In which component of the compilation process the annotation occurred.
                        - `apiDescriptionParser`
                        - `parametersValidation`
                        - `uriTemplateExpansion`
                    - code (number) - Parser-specific code of the annotation.
                    - message (string) - Textual annotation. This is – in most cases – a human-readable message to be displayed to user.
                    - location (array) - Locations of the annotation in the source file. A series of character-blocks, which may be non-continuous. For further details refer to API Elements' [Source Map](source-map) element.
                        - (array, fixed) - Continuous characters block. A pair of character index and character count.
                            - (number) - Zero-based index of a character in the source document.
                            - (number) - Count of characters starting from the character index.
                    - origin (object) - Object of references to nodes of [API Elements][api-elements] derived from the original API description document.
                        - filename: `./blueprint.md` (string)
                        - apiName: `My Api` (string)
                        - resourceGroupName: `Greetings` (string)
                        - resourceName: `Hello, world!` (string)
                        - actionName: `Retrieve Message` (string)
                        - exampleName: `First example` (string)
    - public: true (boolean) - True if test run results are public
    - logs (array) - an Array of logs from hooks
    - agent (string) - Who performed the test
    - agentRunUuid (string) - UUID v4 generated by the agent for particular test run identification
    - hostname (string) - Hostname of computer where test run was preformed. FQDN is not necessary.
    - agentEnvironment (object, optional) - Run agent environment data from CI, development, staging, production etc...
    - startedAt (number) - Unix timestamp when test run started in UTC
    - createdAt (string) - Date in ISO format
    - endedAt (number) - Unix timestamp when test run ended in UTC
    - status (string) - Test run result
    - Values
        - `success`
        - `fail`
        - `running`
    - result (object) Result report
    - tests
    - failures
    - passes


#### Create test run [POST]

- Request (application/json)

    - Headers

            Authentication: Token aff888af9993db9ef70edf3c878ab521

    - Body

            {
              "_id": "507f1f77bcf86cd799439011",
              "endpoint": "http://localhost:3000",
              "blueprints": [
                {
                  "raw": "",
                  "filename": "",
                  "annotations": []
                }
              ],
              "agent": "travisci",
              "agentRunUuid": "03b3de07-d354-4ba6-aa2e-28789b03c619",
              "public": true,
              "hostname": "machine.fqdn.tld",
              "agentEnvironment": {
                "CI": "true"
              },
              "startedAt": 1381924285,
              "status": "started"
            }

- Response 201

    - Headers

            Content-Type: application/json; charset=utf-8

    - Body

            {
              "_id": "507f1f77bcf86cd799439011",
              "endpoint": "http://localhost:3000",
              "reportUrl": "https://absolutely.fancy.url/wich-can-change/some/id",
              "blueprints": [
                {
                  "raw": "",
                  "filename": "",
                  "annotations": []
                }
              ],
              "public": true,
              "agent": "Dredd/0.1.7 (Linux 3.2.0-23-generic; x64)",
              "agentRunUuid": "03b3de07-d354-4ba6-aa2e-28789b03c619",
              "hostname": "machine.fqdn.tld",
              "agentEnvironment": {
                "CI": "true"
              },
              "startedAt": 1381924285,
              "status": "started"
            }


#### Retrieve multiple test runs [GET]

- Request

    - Headers

            Authentication: Token aff888af9993db9ef70edf3c878ab521

- Response 200

    - Headers

            Content-Type: application/json; charset=utf-8

    - Body

            [
              {
                "_id": "507f1f77bcf86cd799439011",
                "endpoint": "http://localhost:3000",
                "reportUrl": "https://absolutely.fency.url/wich-can-change/some/id",
                "blueprints": [
                  {
                    "raw": "",
                    "filename": "",
                    "annotations": []
                  }
                ],
                "logs": [],
                "public": true,
                "agent": "Dredd/0.1.7 (Linux 3.2.0-23-generic; x64)",
                "agentRunUuid": "03b3de07-d354-4ba6-aa2e-28789b03c619",
                "hostname": "machine.fqdn.tld",
                "agentEnvironment": {
                  "CI": "true"
                },
                "startedAt": 1381924285,
                "status": "started"
              }
            ]


### Test run [/apis/{suite}/tests/run/{id}]

- Parameters
    - suite: jakubtest (string, required) - API suite domain identificator
    - id: 507f1f77bcf86cd799439011 (string, required) - Unique id of the run in Apiary


#### Update Attributes [PATCH]

- Request (application/json)

    - Headers

            Authentication: Token aff888af9993db9ef70edf3c878ab521

    - Body

            {
              "logs": [{
                "timestamp": 1381924294,
                "content": "Log message from hooks"
              }],
              "endedAt": "1381924299",
              "status": "passed",
              "result": {
                "tests": 7,
                "failures": 0,
                "passes": 7
              }
            }

- Response 200
    - Headers

            Content-Type: application/json; charset=utf-8

    - Body

            {
              "_id": "507f1f77bcf86cd799439011",
              "endpoint": "http://localhost:3000",
              "reportUrl": "https://absolutely.fancy.url/wich-can-change/some/id",
              "blueprints": [
                {
                  "raw": "",
                  "filename": "",
                  "annotations": []
                }
              ],
              "logs": [{
                "timestamp": 1381924294,
                "content": "Log message from hooks"
              }],
              "public": true,
              "agent": "Dredd/0.1.7 (Linux 3.2.0-23-generic; x64)",
              "agentRunUuid": "03b3de07-d354-4ba6-aa2e-28789b03c619",
              "hostname": "machine.fqdn.tld",
              "agentEnvironment": {
                "CI": "true"
              },
              "startedAt": 1381924285,
              "endedAt": "1381924299",
              "status": "passed",
              "result": {
                "tests": 7,
                "failures": 0,
                "passes": 7
              }
            }


## Group Test Steps

- Attributes
    - _id (string) - Unique object id. DO NOT USE IT WHEN CREATING! Used in post body only for purpose of testing this blueprint.
    - testRunId (string) - Reference to the parent test run identificator
    - origin (object) - Origin path (position, location) of the step in the blueprint AST
        - filename (string) - File name of original blueprint
        - uriTemplate (string) - URI Template used as source for URL of this step
        - resourceGroupName (string) - Group name
        - resourceName (string) - Resource name
        - actionName (string) - Action name
        - exampleName (string) - Example name
    - duration (number) - Test duration in seconds
    - result (string) - Result of step execution
        - Values
            - `passed`
            - `failed`
    - resultData (object) - Data from step execution
        - request (object) - [Real HTTP Request](https://www.relishapp.com/apiary/gavel/docs/data-model#http-request)
        - realResponse (object) - [Real HTTP response](https://www.relishapp.com/apiary/gavel/docs/data-model#http-response)
        - expectedResponse (object) - [Expected HTTP Response](https://www.relishapp.com/apiary/gavel/docs/data-model#expected-http-response)
        - result (object) - [Validation result output](https://www.relishapp.com/apiary/gavel/docs/data-validators-and-output-format#validators-output-format)
    - stepType (string, `exampleNameTransactionName`) - Type of the step, should be HTTP or Cucumber for instance

### Test steps collection [/apis/{suite}/tests/steps{?testRunId,include}]

- Parameters
    - suite: jakubtest (string, required) - API suite domain identificator
    - testRunId: 507f1f77bcf86cd799439011 (string, required) -  Retreive steps by run
    - include: resultData (string) - Include result data in the response body

#### Create [POST]

- Request (application/json)

    - Headers

            Authentication: Token aff888af9993db9ef70edf3c878ab521

    - Body

            {
              "_id": "507c7f79bcf86cd7994f6c0e",
              "testRunId": "507f1f77bcf86cd799439011",
              "origin": {
                "filename": "./apiary.apib",
                "uriTemplate": "/",
                "resourceGroupName": "Machines",
                "resourceName": "Machines collection",
                "actionName": "Create a machine",
                "exampleName": ""
              },
              "duration": 12.345,
              "result": "fail",
              "stepType": "exampleNameTransaction",
              "result": "passed",
              "resultData": {
                "request": {
                  "uri": "/",
                  "method": "GET",
                  "headers": {
                    "content-type": "application/json"
                  },
                  "body": ""
                },
                "realResponse": {
                  "statusCode": "200",
                  "statusMessage": "OK",
                  "headers": {
                    "content-type": "application/json"
                  },
                  "body": "{\"name\": \"My api\", \"kind\": \"Cool API\"}"
                },
                "expectedResponse": {
                  "statusCode": "200",
                  "statusMessage": "OK",
                  "headers": {
                    "content-type": "application/json"
                  },
                  "body": "{\"kind\": \"Cool API\"}"
                },
                "result": {
                  "statusCode": {
                  },
                  "headers": {
                  },
                  "body": {
                  }
                }
              }
            }

- Response 201

  -  Headers

            Content-Type: application/json; charset=utf-8

  - Body

            {
              "_id": "507c7f79bcf86cd7994f6c0e",
              "testRunId": "507f1f77bcf86cd799439011",
              "origin": {
                "filename": "./apiary.apib",
                "uriTemplate": "/",
                "resourceGroupName": "Machines",
                "resourceName": "Machines collection",
                "actionName": "Create a machine",
                "exampleName": ""
              },
              "duration": 12.345,
              "result": "fail",
              "stepType": "exampleNameTransaction",
              "result": "passed",
              "resultData": {}
            }

#### Retrieve [GET]

- Request (application/json)

    - Headers

            Authentication: Token aff888af9993db9ef70edf3c878ab521

- Response 200

  -  Headers

            Content-Type: application/json; charset=utf-8

  - Body

            [
              {
                "_id": "507c7f79bcf86cd7994f6c0e",
                "testRunId": "507f1f77bcf86cd799439011",
                "origin": {
                  "filename": "./apiary.apib",
                  "uriTemplate": "/",
                  "resourceGroupName": "Machines",
                  "resourceName": "Machines collection",
                  "actionName": "Create a machine",
                  "exampleName": ""
                },
                "duration": 12.345,
                "result": "passed",
                "stepType": "exampleNameTransaction",
                "resultData": {}
              }
            ]

### Test step [/apis/{suite}/tests/step/{id}{?include}]

####  Retreive [GET]

- Parameters
    - suite: jakubtest (string, required) - API suite domain identificator
    - id: 507c7f79bcf86cd7994f6c0e (string, required) - Unique identifier of test step in Apiary
    - include: resultData (string) - Include result data in the response body

- Request (application/json)

    - Headers

            Authentication: Token aff888af9993db9ef70edf3c878ab521

- Response 200

    - Headers

            Content-Type: application/json; charset=utf-8

  - Body

            {
              "_id": "507c7f79bcf86cd7994f6c0e",
              "testRunId": "507f1f77bcf86cd799439011",
              "origin": {
                "filename": "./apiary.apib",
                "uriTemplate": "/",
                "resourceGroupName": "Machines",
                "resourceName": "Machines collection",
                "actionName": "Create a machine",
                "exampleName": ""
              },
              "duration": 12.345,
              "result": "fail",
              "stepType": "exampleNameTransaction",
              "resultData": {
              }
            }