Welcome to Copr Api 2’s documentation!

Welcome to the documentation of the new REST-like API for the Copr build service. Almost all API calls are done using application/json ContentType.

Endpoint of the the API is /api_2, public data is available without authorization.

To create new projects, submit builds and do other modification requests, you need to provide an API token using BasicAuth . The token can be obtained and renewed at the CoprAPI page.

Resources

• Project
  • Structure of the project entity
  • List projects
  • Create new project
  • Get project details
  • Delete project
  • Modify project
• Project Chroot
  • Structure of the project chroot entity
  • List project chroots
  • Enable chroot for project
  • Get project chroot details
  • Disable chroot for project
  • Modify project chroot
• Build
  • Structure of the build entity
  • List builds
  • Submit new build
  • Get build details
  • Cancel build
  • Delete build
• Build Task
  • Structure of the build task entity
  • List build tasks
  • Get build task details
• Mock Chroot
  • Structure of the mock chroot entity
  • List mock chroots
  • Get mock chroot details

HATEOAS

This API implements HATEOAS in the very simple form: each entity is accompanied with a set of relative links to other related entities. HATEOAS makes API self discoverable, so you don’t need to learn how to access sub-resources. Here is a short example with the content of API root:

GET /api_2

{
  "_links": {
    "mock_chroots": {
      "href": "/api_2/mock_chroots"
    },
    "self": {
      "href": "/api_2/"
    },
    "projects": {
      "href": "/api_2/projects"
    },
    "builds": {
      "href": "/api_2/builds"
    }
    "build_tasks": {
      "href": "/api_2/build_tasks"
    }
}

Response structure

Each entity is enveloped into a json dict and accompanied with set of HATEOAS references. GET requests would return the following structures:

Collection structure:

A collection provides information about several objects.

{
    "_links" {
        "self": {
            "href": "<url which was used to obtain current collection>"
        },
        "<relation name>": {
            "href": "<relation url>"
        }
    },
    "<collection name>": [
        {<individual 1>},
        {<individual 2>},
        {
            "_links": {...},
            "<entity name>": {<entity structure>}
        }
    ]
}

Individual structure:

An individual provides information about one object.

{
    "_links": {
        "self": {
            "href": "<url which was used to obtain the object>"
        },
        "<relation name>": {
            "href": "<relation url>"
        }
    },
    "<entity name>": {<entity structure>}
}

Errors

To distinguish errors, we use standard HTTP codes: https://en.wikipedia.org/wiki/List_of_HTTP_status_codes. Additional information may be contained in the response body, which SHOULD have application/json Content-Type. Inside json object, there will always be a key message with error description. In some cases, an additional information would be present at key data.

Example

GET /api_2/builds?project_id=999999999 HTTP/1.1
Host: copr.fedoraproject.org

Response

HTTP/1.1 404 NOT FOUND
Content-Type: application/json

{
  "message": "Project with id `999999999` not found",
  "data": {
    "project_id": 999999999
  }
}