User Tools



Web API

Testspace provides a REST API, designed to have predictable, resource-oriented URLs that leverage built in features of HTTP, like authentication, verbs and response codes. All data is sent and received in JSON format and UTF-8 encoding. Any off-the-shelf HTTP client can be used to communicate with the API.

Authentication

Testspace API is authenticated using HTTP Basic Auth over HTTPS. Any requests over plain HTTP will fail.

The credentials may be given either as username:password or as access-token:1).

For example using curl you can pass the -u flag:

$ curl -u <credentials> "https://domain.testspace.com/api/projects"

or set the Authorization header:

$ curl -H "Authorization: Basic <base64-encoded-credentials>" "https://domain.testspace.com/api/projects"

All requests are associated with a specific user in Testspace and permissions are limited to that user's capabilities.

Requests

The base URL of the API is https://domain.testspace.com/api where domain should be replaced with your organization subdomain.

Parameters

Many API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter:

$ curl -u username:password "https://domain.testspace.com/api/projects/123/spaces?name=ABC"

In this example, the value '123' is provided for the project :id parameter in the path while :name is passed in the query string.

For POST, PATCH, PUT, and DELETE requests, parameters not included in the URL must be encoded as JSON with a Content-Type of application/json, or the API will return a 415 Unsupported Media Type status code:

$ curl -u username:password "https://domain.testspace.com/api/spaces/1234" \
    -X PATCH \
    -H 'Content-Type: application/json' \
    -d '{"description":"some description"}'

HTTP Verbs

The API strives to use appropriate HTTP verbs for each action:

  • GET - To retrieve a resource or a collection of resources
  • POST - To create a resource
  • PATCH or PUT - To modify a resource
  • DELETE - To delete a resource

Responses

All response bodies, including errors, are JSON encoded with a Content-Type of application/json.

A single resource is represented as a JSON object:

{
  "field1": "value",
  "field2": true,
  "field3": []
}

A collection of resources is represented as a JSON array of objects:

[
  {
    "field1": "value",
    "field2": true,
    "field3": []
  },
  {
    "field1": "another value",
    "field2": false,
    "field3": []
  }
]

All timestamps are returned in ISO 8601 format.

Unset fields will be represented as a null instead of being omitted. If the field is an array, it will be represented as an empty array - i.e. [].

Errors

The API uses HTTP status codes to indicate success or failure of a request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. authentication failed, a resource not found, a validation error, etc.), and codes in the 5xx range indicate an internal server error.

All 4xx series errors will be returned with a JSON object in the body:

{
   "message": "Not Found"
}

5xx series error codes do not return JSON bodies.

Projects

All the information in Testspace is organized in projects. A project contains one or more Spaces.

Field Type Notes
id integer The unique ID of the project
name string The name of the project
description string The description of the project
is_private boolean True if the project is private, false otherwise
updated_at timestamp The date/time when the project was last updated
created_at timestamp The date/time when the project was created

To request details about projects and to create or modify projects use the following API methods.

Listing projects

GET /api/projects

A successful response includes an array of projects, as each entry in the list follows the same format as getting a single project:

200 OK
Content-Type: application/json
[
  { "id": 123, "name": ... },
  { "id": 345, "name": ... },
  ...
]

Getting a single project

GET /api/projects/:project_id
:project_id The ID of a project

A successful response looks like:

200 OK
Content-Type: application/json
{ 
  "id": 123,
  "name": "MyProject",
  "description": "Some description for my project",
  "is_private": true,
  "created_at": "2014-10-06T18:02:54Z",
  "updated_at": "2014-12-04T19:59:42Z"
}

Creating a new project

POST /api/projects
Field Required Notes
name yes The name of the project
description no The description of the project
is_private no True if the project is private, false otherwise

Sample request:

POST /api/projects
Content-Type: application/json
{ 
  "name": "MyProject",
  "description": "Some description for my project",
}

A successful response returns the new project following the same format as getting a single project:

201 Created
Location: https://domain.testspace.com/api/projects/123
Content-Type: application/json
{ 
  "id": 123,
  "name": "MyProject",
  ...
}

Updating a project

PATCH /api/projects/:project_id
:project_id The ID of a project
Field Required Notes
name no The name of the project
description no The description of the project
is_private no True if the project is private, false otherwise

Sample request:

PATCH /api/projects/123
Content-Type: application/json
{ 
  "name": "NewProject",
}

A successful response returns the updated project following the same format as getting a single project:

205 Reset Content
Content-Type: application/json
{ 
  "id": 123,
  "name": "NewProject",
  ...
}

Deleting a project

DELETE /api/projects/:project_id
:project_id The ID of a project

Sample request:

DELETE /api/projects/123

A successful response returns no content:

204 No Content

Spaces

Each Project consists of Spaces. A Space is a collection of test test results.

Field Type Notes
id integer The unique ID of the space
name string The name of the space
description string The description of the space
project_id integer The associated project
is_hidden boolean True if the space is hidden, false otherwise
min_run_period integer Publication deadline for results in days (0 to disable)
active_result_set_id integer The current active (aka latest-complete) result set
latest_result_set_id integer The latest result set
updated_at timestamp The date/time when the space was last updated
created_at timestamp The date/time when the space was created

To request details about spaces and to create or modify spaces use the following API methods.

Listing spaces

GET /api/projects/:project_id/spaces
:project_id The ID of the associated project

A successful response includes an array of space, as each entry in the list follows the same format as getting a single space:

200 OK
Content-Type: application/json
[
  { "id": 1234, "name": ... },
  { "id": 5678, "name": ... },
  ...
]

Getting a single space

GET /api/spaces/:space_id
:space_id The ID of a space

A successful response looks like:

200 OK
Content-Type: application/json
{ 
  "id": 1234,
  "name": "MySpace",
  "description": "Some description for my space",
  "project_id": 12,
  "is_hidden": false,
  "min_run_period": 1,
  "active_result_set_id": 10823,
  "latest_result_set_id": 10823
  "created_at": "2014-10-06T18:02:54Z",
  "updated_at": "2014-12-04T19:59:42Z"
}

Creating a new space

POST /api/projects/:project_id/spaces
:project_id The ID of the associated project
Field Required Notes
name yes The name of the space
description no The description of the space
is_hidden no True for hidden space, false otherwise
min_run_period no Publication deadline for results in days (0 to disable)

Sample request:

POST /api/projects/12/spaces
Content-Type: application/json
{ 
  "name": "MySpace",
  "description": "Some description for my space",
}

A successful response returns the new space following the same format as getting a single space:

201 Created
Location: https://domain.testspace.com/api/spaces/1234
Content-Type: application/json
{ 
  "id": 1234,
  "name": "MySpace",
  ...
}

Updating a space

PATCH /api/spaces/:space_id
:space_id The ID of a space
Field Required Notes
name no The name of the space
description no The description of the space
is_hidden no True for private hidden, false otherwise
min_run_period integer Publication deadline for results in days (0 to disable)

Sample request:

PATCH /api/spaces/1234
Content-Type: application/json
{ 
  "name": "NewSpace",
}

A successful response returns the updated space following the same format as getting a single space:

205 Reset Content
Content-Type: application/json
{ 
  "id": 1234,
  "name": "NewSpace",
  ...
}

Deleting a space

DELETE /api/spaces/:space_id
:space_id The ID of a space

Sample request:

DELETE /api/spaces/1234

A successful response returns no content:

204 No Content
1) You can generate and get an Access token from your User Settings

Page Tools