api2.md

#Copr Api v2

Here I propose a second version of the Copr Api.
Main reasons: to make api more RESTful-like and uniform.
Features:

• each entity should be represented by resource
• ... and grouped in collections (is entity have parent or owner)
• more clear URL schema
• CRUD operations through HTTP codes
• return operation results using HTTP status codes (BZ:#1128362)
• cleanup of different name for the same objects

Transition:

Added /api2/, keep old /api/ for the current users.
Makes copr-cli use /api2/. When nobody will use old api, remove it.

Authentication

No changes from the previous api.
Basic http auth with login and token provided at /api/ page.

User

/api/users/

GET

###/api/users/

Returns users collection
Parameters: None
Body: None
Response: 200 OK

[
    {
        "user": "jdoe", 
        "href": "/api/users/jdoe/"
    },
    ...
]

###/api/users/?filter=substring

Returns users collections filtered by substring

/api/users/{username}/

Returns detail information about the user:
Response: 200 OK

{
    "user": "jdoe",
    "projects_count": 5,
    "projects_href": "/api/users/jdoe/coprs/"
}

POST

/api/users/

Creates new user, if name is free.
Body:

{
    "user": "jdoe", 
    "href": "/api/users/jdoe/"
}

(In fact this is more complex, since new user created from fedoraproject openid. Let's postpone it for now) Response: 201 Created

DELETE

###/api/users/

Auth required!
Deletes entire user section along with all projects and build.

Projects(or Coprs)

/api/users/{user}/coprs/

GET

/api/users/{user}/coprs/

Lists all projects created by the user.
Returns:

[
    {
        "projectname": "foo", 
        "description": "...", 
        "href": "/api/users/<user>/coprs/foo/",
        ...  
    }
]

/api/users/{user}/coprs/{projectname}/

Project details
Returns:

{
    "name": "foo",
    "description": "Lorem ipsum dolor sit amet, consectetur adipisicing elit",
    "instructions": "...",
    "chroots": [
        {   
            "chroot": "fedora-19-i686",
            "result_repo": "https://cop ... ra-19-i686/",
            "href": "/api/users/<user>/coprs/<projectname>/"
        },
        ...
    ],
    "chroots_href": "/api/users/<user>/coprs/<projectname>/chroots",
    "additional_repos": [],
    "last_successful_build": 12345,
    "last_successful_build_time": 1246236236,
}

**NOTE!: ** field last_modified is misleading and to replaced with last_successful_build_time. Also frontend shall provide correct Http-Header Last-modified for all resources

POST

/api/users/{user}/coprs/

Auth required!
Creates new copr.
Body:

{   
    "projectname": "foo", 
    "description": "...:",
    "instructions": "...",
    "chroots": ["epel-6-x86_64", "fedora-19-i686"],
    "additional_repos": ["repo_url_0", "repo_url_1"]
}

on success: Response: 201 Created

{
    "id": 12345,
    "description": "...",
    "instructions": "...",
    "chroots": [
        ...
    ],
    "chroots_href": "/api/users/<user>/coprs/<projectname>/chroots",
    "additional_repos": [],
    "last_successful_build": nil,
    "last_successful_build_time"
}

if the user already has project with the same projectname: Response: 409 Conflict

PUT

/api/users/{user}/coprs/{projectname}

Auth required!_
Modifies project.
Body:

{   
    "description": "...:",
    "instructions": "...",
    "additional_repos": ["repo_url_0", "repo_url_1"]
}

Response: 200 OK *NOTE chroots are to be modified through Chroot resource

DELETE

/api/users/{user}/coprs/

Auth required!_
Deletes entire project with all builds.
Response: 200 OK

Builds

/api/users/{user}/coprs/{projectname}/builds/

GET

/api/users/{user}/coprs/{projectname}/builds/

Lists all builds in projectname Response: 200 OK

[
    {   "id": 12345, 
        "src_package": "http://asamalik.fedorapeople.org/hello-2.8-1.fc20.src.rpm",
        "status": pending,
        ... // see next section
    }
]

/api/users/{user}/coprs/{projectname}/builds/{build_id}

Shows build details List all builds in projectname Response: 200 OK

{   "id": 12345, 
    "src_package": "http://asamalik.fedorapeople.org/hello-2.8-1.fc20.src.rpm",
    "src_version": "2.8",
    "status": pending,
    "owner": "user",
    "submiter_by: "another_user",
    "submitted_on": 1386695673,
    "started_on": 1386695985,
    "ended_on": 1386696854,
    "chroots": {
        "fedora-20-i386": "succeeded",
        "fedora-20-x86_64": "succeeded"
    },
    "built_pkgs": [
        "hello 2.8",
        "hello-gui 2.8",
        "super-lib 5.4"
    ],
 }

/api/builds/{build_id}/

Redirect to the proper location
if build founded return redirect: 302 Found
otherwise response: 404 Not Found

/api/builds/?package=python&chroot=epel-7-x86_64

Performs search of builds across all users and projects Response: 200 OK

[
    {   
        "id": 12345,
        "username": "jdoe",
        "projectname": "foobar",
        "href": "/api/users/jdoe/coprs/foobar/builds/12345"
    },
    ...
]

POST

/api/users/{user}/coprs/{projectname}/builds/

Creates new build(s). Produces build entity for each source package.

{   
    "src_packages": [ "src_url1", "src_url2", ...]
    "chroots": [
        "fedora-20-i386",
        "fedora-20-x86_64"
    },
}```

> Response: **200 OK**
```json
[
    {   
        "id": 12345,
        "username": "jdoe",
        "projectname": "foobar",
        "href": "/api/users/jdoe/coprs/foobar/builds/12345"
    },
    ...
]

PUT

/api/users/{user}/coprs/{projectname}/builds/{build_id}/

Modifies build. Also should be used to cancel build by passing status=cancel in json body.
Include only fields which should be changed Body:

{
    "status": "cancel",
}

or

{
    "chroot": ["fedora-20-i386",]
}

Response: 200 OK

DELETE

/api/users/{user}/coprs/{projectname}/builds/{build_id}/

Chroots

api/users/{user}/coprs/{projectname}/chroots/

GET

api/users/{user}/coprs/{projectname}/chroots/

api/users/{user}/coprs/{projectname}/chroots/{chroot}

POST

api/users/{user}/coprs/{projectname}/chroots/

PUT

api/users/{user}/coprs/{projectname}/chroots/{chroot}

DELETE

api/users/{user}/coprs/{projectname}/chroots/{chroot}