[copr] master: [doc][api 2] build review + add submitter to the API (64cf275)

Repository : http://git.fedorahosted.org/cgit/copr.git On branch : master commit 64cf2750b271d96762c65920a91d5759e370e10a Author: Adam Samalik <asamalik(a)redhat.com&gt; Date: Thu Sep 10 17:04:38 2015 +0200 [doc][api 2] build review + add submitter to the API frontend/docs/api_2/source/Resources/build.rst | 87 ++++++++++++++++------ frontend/docs/api_2/source/Resources/project.rst | 6 +- 2 files changed, 70 insertions(+), 23 deletions(-) diff --git a/frontend/docs/api_2/source/Resources/build.rst b/frontend/docs/api_2/source/Resources/build.rst index f90b5ef..66c85ac 100644 --- a/frontend/docs/api_2/source/Resources/build.rst +++ b/frontend/docs/api_2/source/Resources/build.rst @@ -1,10 +1,10 @@ Build ===== -Build resources allows to submit new builds and access current build progress. +Build resource allows to submit new builds and access current build progress. -Build in fact consists of the few tasks, one per chroot, and detail information -is available through sub-resource :doc:`./build_task`. +In fact, build consists of a few tasks, one per chroot, and detailed information +is available through resource :doc:`./build_task`. @@ -37,7 +37,8 @@ Structure of the build entity "ended_on": 1440754058, "package_version": "2.0.0b5-1.fc22", "package_name": "python-marshmallow", - "id": 106882 + "id": 106882, + "submitter": "asamalik" } @@ -58,19 +59,20 @@ package_name string name of the source package enable_net bool defines if network is available during the build repos list of string list of additional repositories enabled during the build built_packages list of hash maps list of the built packages, each hash map has two keys: ``name`` and ``version`` +submitter string name of the user who submitted the build ================== ==================== =============== .. note:: Only the ``state`` field is editable by the PUT method. - All other fields are read only. - There is a different structure used for build creation, see details at `Submit new build`_ + All other fields are read-only. + There is a different structure used for build creation, see details at `Submit new build`_. List builds ----------- .. http:post:: /api_2/builds - Return a list of build according to the given query parameters. + Returns a list of builds according to the given query parameters. :query str owner: select only builds from projects owned by this user :query str project_id: select only projects owned by this project @@ -131,7 +133,8 @@ List builds "state": "succeeded", "ended_on": 1441366969, "id": 106897, - "repos": [] + "repos": [], + "submitter": "asamalik" } } ] @@ -140,11 +143,11 @@ List builds Submit new build ---------------- -**REQUIRE AUTH** +**REQUIRES AUTH** -Allows to submit new build. Copr services currently provides the following options for build submission: +There are more ways to submit new build. Copr services currently provides the following options for build submission: -From srpm url +From SRPM URL ~~~~~~~~~~~~~ .. code-block:: javascript @@ -159,8 +162,8 @@ From srpm url Field Type Description ================== ==================== =============== project_id int identifier of the parent project - chroots list of strings what chroots should be used for build - srpm_url string(URL) url to the publicly available source package + chroots list of strings which chroots should be used for build + srpm_url string(URL) URL to the publicly available source package enable_net bool allows to disable network access during the build, default: True ================== ==================== =============== @@ -197,14 +200,14 @@ From srpm url HTTP/1.1 201 CREATED Location: /api_2/builds/106897 -Using file upload -~~~~~~~~~~~~~~~~~ +Using SRPM file upload +~~~~~~~~~~~~~~~~~~~~~~ To upload source package you MUST use ``multipart/form-data`` content type. -Addition build information MUST present in ``metadata`` part in JSON format. Source package +An additional build information MUST be present in ``metadata`` part in JSON format. Source package MUST be uploaded as binary ``srpm`` file. - **Build info** + **** .. code-block:: javascript @@ -226,8 +229,8 @@ MUST be uploaded as binary ``srpm`` file. .. http:post:: /api_2/builds :reqheader Content-Type: MUST be a ``multipart/form-data`` - :formparam metadata: JSON with the build info - :formparam srpm: file with source package + :formparam metadata: JSON with the build info, MUST have a content type ``application/json`` + :formparam srpm: file with source package, MUST have a content type ``application/x-rpm`` :resheader Location: contains URL to the created build @@ -235,7 +238,46 @@ MUST be uploaded as binary ``srpm`` file. :statuscode 400: user data doesn't satisfy some requirements :statuscode 403: authorization failed - **Example** + .. note:: Using a ``multipart/form-data`` might not be nice to read. To make your life a bit brighter, a Python example is included below. + + **Example request**: + + .. sourcecode:: http + + POST /api_2/builds HTTP/1.1 + Host: copr.fedoraproject.org + Authorization: Basic base64=encoded=string + Content-Length: xxxx + Content-Type: multipart/form-data; boundary=--------------------31063722920652 + + ------------------------------31063722920652 + Content-Disposition: form-data; name="metadata" + Content-Type: application/json + + { + "project_id": 3985, + "chroots": ["fedora-22-i386", "fedora-21-i386"], + "enable_net": false + } + + ------------------------------31063722920652 + Content-Disposition: form-data; name="srpm"; filename="package-2.6-fc21.src.rpm" + Content-Type: application/x-rpm + + << SRPM BINARY CONTENT HERE >> + + -----------------------------31063722920652-- + + + **Response**: + + .. sourcecode:: http + + HTTP/1.1 201 CREATED + Location: /api_2/builds/106897 + + + **Python Example**: Here we use python-requests_ lib: @@ -340,7 +382,8 @@ Get build details "state": "succeeded", "ended_on": 1441366969, "id": 106897, - "repos": [] + "repos": [], + "submitter": "asamalik" } } @@ -384,7 +427,7 @@ Delete build **REQUIRE AUTH** - Deletes build and schedules deletion of build result at Copr backend + Deletes build and schedules deletion of build result from the Copr backend :param int build_id: a unique identifier of the build diff --git a/frontend/docs/api_2/source/Resources/project.rst b/frontend/docs/api_2/source/Resources/project.rst index ce9a49b..71324c5 100644 --- a/frontend/docs/api_2/source/Resources/project.rst +++ b/frontend/docs/api_2/source/Resources/project.rst @@ -202,6 +202,9 @@ Get project details "_links": { }, "build": { "enable_net": true, + "source_metadata": { + "url": "http://miroslav.suchy.cz/copr/copr-ping-1-1.fc20.src.rpm" + }, "submitted_on": 1422379448, "repos": [], "results": "https://copr-be.cloud.fedoraproject.org/results/jmiahman/Synergy-Linux/", @@ -212,7 +215,8 @@ Get project details "ended_on": 1422379584, "timeout": 21600, "pkg_version": "21.6-1.fc21", - "id": 69493 + "id": 69493, + "submitter": "asamalik" } }, { }