Commit 93bf1a48 authored by Gilles Mouchard's avatar Gilles Mouchard
Browse files

Updated "Open source client-side software".

parent e1e06488
Pipeline #18145 passed with stages
in 8 minutes and 37 seconds
......@@ -48,7 +48,7 @@
<img src="pkm-endpoints.png" alt="Figure 2: PKM REST API endpoints" /><figcaption aria-hidden="true">Figure 2: PKM REST API endpoints</figcaption>
</figure>
<p>The white boxes show the paths of the endpoints. The arrows outline the flow for generating new artefacts with parsers. For a reason of limited space, the figure largely underestimates the generation flow of new artefacts when considering the whole DECODER Project tool-chain.</p>
<p>Note that there are some <a href="https://www.openapis.org/">OpenAPI</a> specifications of the REST APIs available on the pkm-api gitlab repository for the followings:</p>
<p>Note that there are some <a href="https://www.openapis.org/">OpenAPI</a> specifications of the REST APIs available on the pkm-api gitlab repository for the following:</p>
<ul>
<li><a href="https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-openapi.yaml">PKM</a></li>
<li><a href="https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/frama-c/api/frama-c-openapi.yaml">Frama-C for PKM</a></li>
......
......@@ -55,7 +55,7 @@ The white boxes show the paths of the endpoints.
The arrows outline the flow for generating new artefacts with parsers.
For a reason of limited space, the figure largely underestimates the generation flow of new artefacts when considering the whole DECODER Project tool-chain.
Note that there are some [OpenAPI](https://www.openapis.org/) specifications of the REST APIs available on the pkm-api gitlab repository for the followings:
Note that there are some [OpenAPI](https://www.openapis.org/) specifications of the REST APIs available on the pkm-api gitlab repository for the following:
* [PKM](https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-openapi.yaml)
* [Frama-C for PKM](https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/frama-c/api/frama-c-openapi.yaml)
......
......@@ -33,7 +33,7 @@
&quot;dont_delete_git_working_tree_files&quot;: false
}
}</code></pre>
<p>This runs the git command sequence passed in request body in the project with the given name <code>{dbName}</code>. Commands <code>cd</code> or <code>chdir</code> in the command sequence allows changing the working directory to execute subsequent commands within a Git working tree. The operation returns in the response body a Git job which client can poll when in asynchronous mode (i.e. <code>asynchronous=true</code>) using the property <code>id</code> of the job as a job identifier. When in asynchronous mode, the job is enqueued in a job queue. The default behavior is to run jobs synchronously. Section 6.2 describes the role of the <code>dont_delete_pkm_files</code> and <code>dont_delete_git_working_tree_files</code> properties in the request body which are optional.</p>
<p>This runs the git command sequence passed in request body in the project with the given name <code>{dbName}</code>. Commands <code>cd</code> or <code>chdir</code> in the command sequence allow changing the working directory to execute subsequent commands within a Git working tree. The operation returns in the response body a Git job which client can poll when in asynchronous mode (i.e. <code>asynchronous=true</code>) using the property <code>id</code> of the job as a job identifier. When in asynchronous mode, the job is enqueued in a job queue. The default behavior is to run jobs synchronously. Section 6.2 describes the role of the <code>dont_delete_pkm_files</code> and <code>dont_delete_git_working_tree_files</code> properties in the request body which are optional.</p>
<p><strong>Poll a Git job</strong> (REST API 🔐, see GitApi.getGitJob in SDK):</p>
<pre><code>GET /git/job/{jobId}</code></pre>
<p>When a Git job is running asynchronously, this operation allows polling the Git job with the given identifier <code>{jobId}</code> until job completion. The job is dequeued when client polls a completed job (either finished or failed).</p>
......
......@@ -26,7 +26,7 @@ The PKM provides the following operations for supporting Git:
}
This runs the git command sequence passed in request body in the project with the given name `{dbName}`.
Commands `cd` or `chdir` in the command sequence allows changing the working directory to execute subsequent commands within a Git working tree.
Commands `cd` or `chdir` in the command sequence allow changing the working directory to execute subsequent commands within a Git working tree.
The operation returns in the response body a Git job which client can poll when in asynchronous mode (i.e. `asynchronous=true`) using the property `id` of the job as a job identifier.
When in asynchronous mode, the job is enqueued in a job queue.
The default behavior is to run jobs synchronously.
......
......@@ -18,6 +18,16 @@
<div id="content">
<h1 id="document-management">7 Document management</h1>
<p>This chapter describes the operations that the PKM provides to manage documents, i.e. inserting, updating and deleting documents.</p>
<p>In the PKM REST API, these operations correspond to the HTTP POST, PUT, and DELETE requests. These requests can return one the following HTTP status codes:</p>
<ul>
<li>200: The operation is successful.</li>
<li>201: The PKM created a new resource.</li>
<li>400: Bad request. The request has invalid request parameters in the URL, or the format of the request body is malformed. In the latter case, it means that the JSON validation of the input fails against the JSON schema.</li>
<li>401: The operation (labeled with a 🔐 symbol in this document) requires prior authentication (see Section 3).</li>
<li>403: Forbidden operation. The logged in user does not have sufficient rights to perform this operation.</li>
<li>404: Not found; the requested resource does not exist.</li>
<li>500: Internal server error. An error of this type is most likely due to a bug in the PKM server.</li>
</ul>
<h2 id="files">7.1 Files <a id="1"></a></h2>
<p>The PKM REST API models a file as a JSON object with the following properties:</p>
<ul>
......@@ -249,13 +259,13 @@
<h2 id="source-code">7.2 Source Code <a id="2"></a></h2>
<p>The source code parsers (see Section 8.1) provide support for parsing programming languages to the PKM. The PKM stores the resulting intermediate representations (Abstract syntax trees, comments, and annotations) as structured documents (JSON format) in dedicated collections. These structured documents are more suited for implementing queries about elements within the source code (see Section 9.2). These artefacts are all related to a source file, so the source file name which identifies a source file, also uniquely identifies such an artefact. The following subsections present the operations of the PKM API, which are intended for parsers for feeding the PKM with these structured documents.</p>
<h3 id="abstract-syntax-trees-asts">7.2.1 Abstract Syntax Trees (ASTs) <a id="2.1"></a></h3>
<p>The schema for the source code ASTs are available on the pkm-api gitlab repository:</p>
<p>The schemas for the source code ASTs are available on the pkm-api gitlab repository:</p>
<ul>
<li><a href="https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-c-source-code-schema.json">for the C language</a></li>
<li><a href="https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-cpp-source-code-schema.json">for the C++ language</a></li>
<li><a href="https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-java-source-code-schema.json">for the Java language</a></li>
</ul>
<p>The operations for ASTs are the followings:</p>
<p>The operations for ASTs are the following:</p>
<p><strong>Insert or update C source code ASTs</strong> (REST API 🔐, see CodeApi.putCSourceCodes in SDK):</p>
<pre><code>PUT /code/c/sourcecode/{dbName}
[
......@@ -319,12 +329,13 @@
<pre><code>DELETE /code/sourcecode/{dbName}/{filename}</code></pre>
<p>This operation deletes the source code ASTs related to the source code file with the given name <code>{filename}</code> in the project with the given name <code>{dbName}</code>.</p>
<h3 id="comments">7.2.2 Comments <a id="2.2"></a></h3>
<p>The schema for the source code comments are available on the pkm-api gitlab repository:</p>
<p>The schemas for the source code comments are available on the pkm-api gitlab repository:</p>
<ul>
<li><a href="https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-c-comments-schema.json">for the C language</a></li>
<li><a href="https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-cpp-comments-schema.json">for the C++ language</a></li>
<li><a href="https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-java-comments-schema.json">for the Java language</a></li>
</ul>
<p>The operations for source code comments are the followings:</p>
<p>The operations for source code comments are the following:</p>
<p><strong>Insert or update C source code comments</strong> (REST API 🔐, see CodeApi.putCComments in SDK):</p>
<pre><code>PUT /code/c/comments/{dbName}
[
......@@ -336,10 +347,10 @@
<p>This operation inserts the given C comments from the request body into the project with the given name <code>{dbName}</code>, or updates existing C comments into the project with the given name <code>{dbName}</code> with the ones given from the request body.</p>
<p><strong>Delete all C source code comments</strong> (REST API 🔐, see CodeApi.deleteCComments in SDK):</p>
<pre><code>DELETE /code/c/comments/{dbName}</code></pre>
<p>This operation deletes all the C comments of the project with the given name <code>{dbName}</code>.</p>
<p>This operation deletes all the C comments of the project with the given name <code>{dbName}</code>. Note that this operation only affects the intermediate representation of comments in the PKM, not comments in source code files.</p>
<p><strong>Delete C source code comments related to a C source code file</strong> (REST API 🔐, see CodeApi.deleteCCommentsBySourceCodeFilename in SDK):</p>
<pre><code>DELETE /code/c/comments/{dbName}/{filename}</code></pre>
<p>This operation deletes the C comments related to the source code file with the given name <code>{filename}</code> in the project with the given name <code>{dbName}</code>.</p>
<p>This operation deletes the C comments related to the source code file with the given name <code>{filename}</code> in the project with the given name <code>{dbName}</code>. Note that this operation only affects the intermediate representation of comments in the PKM, not comments in source code files.</p>
<p><strong>Insert or update C++ source code comments</strong> (REST API 🔐, see CodeApi.putCPPComments in SDK):</p>
<pre><code>PUT /code/cpp/comments/{dbName}
[
......@@ -351,10 +362,10 @@
<p>This operation inserts the given C++ comments from the request body into the project with the given name <code>{dbName}</code>, or updates existing C++ comments into the project with the given name <code>{dbName}</code> with the ones given from the request body.</p>
<p><strong>Delete all C++ source code comments</strong> (REST API 🔐, see CodeApi.deleteCPPComments in SDK):</p>
<pre><code>DELETE /code/cpp/comments/{dbName}</code></pre>
<p>This operation deletes all the C++ comments of the project with the given name <code>{dbName}</code>.</p>
<p>This operation deletes all the C++ comments of the project with the given name <code>{dbName}</code>. Note that this operation only affects the intermediate representation of comments in the PKM, not comments in source code files.</p>
<p><strong>Delete C++ source code comments related to a C++ source code file</strong> (REST API 🔐, see CodeApi.deleteCPPCommentsBySourceCodeFilename in SDK):</p>
<pre><code>DELETE /code/cpp/comments/{dbName}/{filename}</code></pre>
<p>This operation deletes the C++ comments related to the source code file with the given name <code>{filename}</code> in the project with the given name <code>{dbName}</code>.</p>
<p>This operation deletes the C++ comments related to the source code file with the given name <code>{filename}</code> in the project with the given name <code>{dbName}</code>. Note that this operation only affects the intermediate representation of comments in the PKM, not comments in source code files.</p>
<p><strong>Insert or update Java source code comments</strong> (REST API 🔐, see CodeApi.putJavaComments in SDK):</p>
<pre><code>PUT /code/java/comments/{dbName}
[
......@@ -369,24 +380,24 @@
<p>This operation inserts the given Java comments from the request body into the project with the given name <code>{dbName}</code>, or updates existing Java comments into the project with the given name <code>{dbName}</code> with the ones given from the request body.</p>
<p><strong>Delete all Java source code comments</strong> (REST API 🔐, see CodeApi.deleteJavaComments in SDK):</p>
<pre><code>DELETE /code/java/comments/{dbName}</code></pre>
<p>This operation deletes all the Java comments of the project with the given name <code>{dbName}</code>.</p>
<p>This operation deletes all the Java comments of the project with the given name <code>{dbName}</code>. Note that this operation only affects the intermediate representation of comments in the PKM, not comments in source code files.</p>
<p><strong>Delete Java source code comments related to a Java source code file</strong> (REST API 🔐, see CodeApi.deleteJavaCommentsBySourceCodeFilename in SDK):</p>
<pre><code>DELETE /code/java/comments/{dbName}/{filename}</code></pre>
<p>This operation deletes the Java comments related to the source code file with the given name <code>{filename}</code> in the project with the given name <code>{dbName}</code>.</p>
<p>This operation deletes the Java comments related to the source code file with the given name <code>{filename}</code> in the project with the given name <code>{dbName}</code>. Note that this operation only affects the intermediate representation of comments in the PKM, not comments in source code files.</p>
<p><strong>Delete all source code comments for any language</strong> (REST API 🔐, see CodeApi.deleteSourceCodeComments in SDK):</p>
<pre><code>DELETE /code/comments/{dbName}</code></pre>
<p>This operation deletes all the source code comments of the project with the given name <code>{dbName}</code>.</p>
<p>This operation deletes all the source code comments of the project with the given name <code>{dbName}</code>. Note that this operation only affects the intermediate representation of comments in the PKM, not comments in source code files.</p>
<p><strong>Delete source code comments for any language related to a source code file</strong> (REST API 🔐, see CodeApi.deleteSourceCodeCommentsBySourceCodeFilename in SDK):</p>
<pre><code>DELETE /code/comments/{dbName}/{filename}</code></pre>
<p>This operation deletes the source code comments related to the source code file with the given name <code>{filename}</code> in the project with the given name <code>{dbName}</code>.</p>
<p>This operation deletes the source code comments related to the source code file with the given name <code>{filename}</code> in the project with the given name <code>{dbName}</code>. Note that this operation only affects the intermediate representation of comments in the PKM, not comments in source code files.</p>
<h3 id="annotations">7.2.3 Annotations <a id="2.3"></a></h3>
<p>The schema for the source code annotations are available on the pkm-api gitlab repository:</p>
<p>The schemas for the source code annotations are available on the pkm-api gitlab repository:</p>
<ul>
<li><a href="https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-acsl-schema.json">for the C language</a> (<a href="https://frama-c.com/html/acsl.html">ACSL</a>)</li>
<li><a href="https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-acslpp-schema.json">for the C++ language</a> (<a href="https://frama-c.com/html/acsl.html">ACSL++</a>)</li>
<li><a href="https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/jml-schema.json">for the Java language</a> (<a href="http://www.openjml.org">OpenJML</a>)</li>
</ul>
<p>The operations for source code annotations are the followings:</p>
<p>The operations for source code annotations are the following:</p>
<p><strong>Insert or update C source code annotations</strong> (REST API 🔐, see CodeApi.putCAnnotations in SDK):</p>
<pre><code>PUT /code/c/annotations/{dbName}
[
......@@ -448,7 +459,7 @@
<li><a href="https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-uml-state-model-schema.json">for the state machines</a></li>
</ul>
<p>The <code>name</code> property of UML classes or UML state machines uniquely identifies these artefacts.</p>
<p>The operations for UML are the followings:</p>
<p>The operations for UML are the following:</p>
<p><strong>Insert UML2 class diagrams</strong> (REST API 🔐, see UMLApi.postUMLClassDiagrams in SDK):</p>
<pre><code>POST /uml/uml_class/{dbName}
[
......@@ -514,7 +525,7 @@
<h2 id="abstract-semi-formal-model-asfm-and-graphical-documentation-in-gsl">7.4 Abstract Semi-Formal Model (ASFM) and Graphical documentation (in GSL) <a id="4"></a></h2>
<p>The schema for ASFM is available on the <a href="https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-asfm-schema.json">pkm-api gitlab repository</a>. The schema for the graphical documentation of a class written in GSL is available on the <a href="https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-gsl-schema.json">pkm-api gitlab repository</a>.</p>
<p>The <code>name</code> property of an ASFM uniquely identifies it. The <code>class</code> and <code>object</code> properties of a class graphical documentation written in GSL uniquely identify it.</p>
<p>The operations for ASFM and the graphical documentation are the followings:</p>
<p>The operations for ASFM and the graphical documentation are the following:</p>
<p><strong>Insert documentation as ASFM</strong> (REST API 🔐, see DocApi.postDocs in SDK):</p>
<pre><code>POST /doc/asfm/docs/{dbName}
[
......@@ -576,7 +587,7 @@
<h2 id="compile-commands">7.5 Compile commands <a id="5"></a></h2>
<p>The <code>file</code> property of a compile command uniquely identifies it.</p>
<p>The schema for the compile commands is available on the <a href="https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-compile-command-schema.json">pkm-api gitlab repository</a>.</p>
<p>The operations for the compile commands are the followings:</p>
<p>The operations for the compile commands are the following:</p>
<p><strong>Insert compile commands</strong> (REST API 🔐, see CompileCommandApi.postCompileCommands in SDK):</p>
<pre><code>POST /compile_command/{dbName}
[
......@@ -612,7 +623,7 @@
<h2 id="common-vulnerabilities-and-exposures-cve">7.6 Common Vulnerabilities and Exposures (CVE) <a id="6"></a></h2>
<p>The schema for CVE entries is available on the <a href="https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-cve-schema.json">pkm-api gitlab repository</a>.</p>
<p>The <code>CVE_data_meta.ID</code> property of a CVE entry uniquely identifies it.</p>
<p>The operations for CVE entries are the followings:</p>
<p>The operations for CVE entries are the following:</p>
<p><strong>Insert CVE entries</strong> (REST API 🔐, see CVEApi.postCVEs in SDK):</p>
<pre><code>POST /cve/{dbName}
[
......@@ -652,7 +663,7 @@
<h2 id="annotations-1">7.7 Annotations <a id="7"></a></h2>
<p>The schema for annotations is available on the <a href="https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-annotations-schema.json">pkm-api gitlab repository</a>.</p>
<p>The <code>path</code> and <code>access</code> properties of an annotation uniquely identify it. The <code>_id</code> property of an annotation that the PKM automatically assigns at insertion is an artefact identifier, which also uniquely identifies the annotation.</p>
<p>The operations for annotations are the followings:</p>
<p>The operations for annotations are the following:</p>
<p><strong>Insert annotations</strong> (REST API 🔐, see AnnotationsApi.postAnnotations in SDK):</p>
<pre><code>POST /annotations/{dbName}
[
......@@ -696,7 +707,7 @@
<h2 id="traceability-matrix">7.8 Traceability Matrix <a id="8"></a></h2>
<p>The schema for the traceability 2D matrix cell is available on the <a href="https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-traceability-matrix-schema.json">pkm-api gitlab repository</a>.</p>
<p>The <code>_id</code> property of a traceability matrix cell that the PKM automatically assigns at insertion, uniquely identifies the traceability matrix cell.</p>
<p>The operations for the traceability matrix are the followings:</p>
<p>The operations for the traceability matrix are the following:</p>
<p><strong>Insert Traceability Matrix cells</strong> (REST API 🔐, see TraceabilityMatrixApi.postTraceabilityMatrix in SDK):</p>
<pre><code>POST /traceability_matrix/{dbName}
[
......@@ -738,7 +749,7 @@
<h2 id="logs-and-reports">7.9 Logs and reports <a id="9"></a></h2>
<p>The schema for logs is available on the <a href="https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-log-schema.json">pkm-api gitlab repository</a>.</p>
<p>The <code>_id</code> property of a log that the PKM automatically assigns at insertion uniquely identifies the log.</p>
<p>The operations for logs are the followings:</p>
<p>The operations for logs are the following:</p>
<p><strong>Insert logs</strong> (REST API 🔐, see LogApi.postLogs in SDK):</p>
<pre><code>POST /log/{dbName}
[
......@@ -787,7 +798,7 @@
</ul>
<p>The TESTAR settings are unique in a project.</p>
<p>The <code>_id</code> property of TESTAR test results or TESTAR state model that the PKM automatically assigns at insertion, uniquely identifies these artefacts.</p>
<p>The operations for TESTAR are the followings:</p>
<p>The operations for TESTAR are the following:</p>
<p><strong>Insert TESTAR settings</strong> (REST API 🔐, see TESTARApi.postTESTARSettings in SDK):</p>
<pre><code>POST /testar/settings/{dbName}
{
......@@ -799,7 +810,7 @@
{
}</code></pre>
<p>This operation inserts the given TESTAR settings from the request body into the project with the given name <code>{dbName}</code>, or update the existing TESTAR settings into the project with the given name <code>{dbName}</code> with the ones given from the request body..</p>
<p>This operation inserts the given TESTAR settings from the request body into the project with the given name <code>{dbName}</code>, or update the existing TESTAR settings into the project with the given name <code>{dbName}</code> with the ones given from the request body.</p>
<p><strong>Delete TESTAR settings</strong> (REST API 🔐, see TESTARApi.deleteTESTARSettings in SDK):</p>
<pre><code>DELETE /testar/settings/{dbName}</code></pre>
<p>This operation deletes the TESTAR settings of the project with the given name <code>{dbName}</code>.</p>
......@@ -861,7 +872,7 @@
<h2 id="reviews">7.11 Reviews <a id="11"></a></h2>
<p>The schema for the reviews is available on the <a href="https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-review-schema.json">pkm-api gitlab repository</a>.</p>
<p>The <code>reviewID</code> property of a review uniquely identifies the review.</p>
<p>The operations for the reviews are the followings:</p>
<p>The operations for the reviews are the following:</p>
<p><strong>Insert reviews</strong> (REST API 🔐, see ReviewsApi.postReviews in SDK):</p>
<pre><code>POST /reviews/{dbName}
[
......@@ -903,7 +914,7 @@
<li><a href="https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-methodology-status-schema.json">for the methodology phases</a></li>
</ul>
<p>The <code>toolID</code> property of a tool specification uniquely identifies it. The <code>invocationID</code> property of a tool invocation uniquely identifies it. The <code>id</code> property of a Methodology phase uniquely identifies it.</p>
<p>The operations for these collections are the followings:</p>
<p>The operations for these collections are the following:</p>
<p><strong>Insert tool specifications</strong> (REST API 🔐, see ToolsApi.postTools in SDK):</p>
<pre><code>POST /tools/{dbName}
[
......@@ -995,7 +1006,7 @@
},
]</code></pre>
<p>This operation inserts the given Methodology status from the request body into the project with the given name <code>{dbName}</code>, or update the existing Methodology status into the project with the given name <code>{dbName}</code> with the ones given from the request body..</p>
<p>This operation inserts the given Methodology status from the request body into the project with the given name <code>{dbName}</code>, or update the existing Methodology status into the project with the given name <code>{dbName}</code> with the ones given from the request body.</p>
<p><strong>Delete Methodology status</strong> (REST API 🔐, see MethodologyApi.deleteMethodologyStatus in SDK):</p>
<pre><code>DELETE /methodology/status/{dbName}?id=…&amp;name=…&amp;phaseNumber=…</code></pre>
<p>This operation deletes the list of Methodology phases in the project with the given name <code>{dbName}</code>.</p>
......
......@@ -2,6 +2,18 @@
This chapter describes the operations that the PKM provides to manage documents, i.e. inserting, updating and deleting documents.
In the PKM REST API, these operations correspond to the HTTP POST, PUT, and DELETE requests.
These requests can return one the following HTTP status codes:
* 200: The operation is successful.
* 201: The PKM created a new resource.
* 400: Bad request. The request has invalid request parameters in the URL, or the format of the request body is malformed.
In the latter case, it means that the JSON validation of the input fails against the JSON schema.
* 401: The operation (labeled with a 🔐 symbol in this document) requires prior authentication (see Section 3).
* 403: Forbidden operation. The logged in user does not have sufficient rights to perform this operation.
* 404: Not found; the requested resource does not exist.
* 500: Internal server error. An error of this type is most likely due to a bug in the PKM server.
## 7.1 Files <a id="1"></a>
The PKM REST API models a file as a JSON object with the following properties:
......@@ -323,13 +335,13 @@ The following subsections present the operations of the PKM API, which are inten
### 7.2.1 Abstract Syntax Trees (ASTs) <a id="2.1"></a>
The schema for the source code ASTs are available on the pkm-api gitlab repository:
The schemas for the source code ASTs are available on the pkm-api gitlab repository:
* [for the C language](https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-c-source-code-schema.json)
* [for the C++ language](https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-cpp-source-code-schema.json)
* [for the Java language](https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-java-source-code-schema.json)
The operations for ASTs are the followings:
The operations for ASTs are the following:
**Insert or update C source code ASTs** (REST API 🔐, see CodeApi.putCSourceCodes in SDK):
......@@ -431,12 +443,13 @@ This operation deletes the source code ASTs related to the source code file with
### 7.2.2 Comments <a id="2.2"></a>
The schema for the source code comments are available on the pkm-api gitlab repository:
The schemas for the source code comments are available on the pkm-api gitlab repository:
* [for the C language](https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-c-comments-schema.json)
* [for the C++ language](https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-cpp-comments-schema.json)
* [for the Java language](https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-java-comments-schema.json)
The operations for source code comments are the followings:
The operations for source code comments are the following:
**Insert or update C source code comments** (REST API 🔐, see CodeApi.putCComments in SDK):
......@@ -455,12 +468,14 @@ This operation inserts the given C comments from the request body into the proje
DELETE /code/c/comments/{dbName}
This operation deletes all the C comments of the project with the given name `{dbName}`.
Note that this operation only affects the intermediate representation of comments in the PKM, not comments in source code files.
**Delete C source code comments related to a C source code file** (REST API 🔐, see CodeApi.deleteCCommentsBySourceCodeFilename in SDK):
DELETE /code/c/comments/{dbName}/{filename}
This operation deletes the C comments related to the source code file with the given name `{filename}` in the project with the given name `{dbName}`.
Note that this operation only affects the intermediate representation of comments in the PKM, not comments in source code files.
**Insert or update C++ source code comments** (REST API 🔐, see CodeApi.putCPPComments in SDK):
......@@ -479,12 +494,14 @@ This operation inserts the given C++ comments from the request body into the pro
DELETE /code/cpp/comments/{dbName}
This operation deletes all the C++ comments of the project with the given name `{dbName}`.
Note that this operation only affects the intermediate representation of comments in the PKM, not comments in source code files.
**Delete C++ source code comments related to a C++ source code file** (REST API 🔐, see CodeApi.deleteCPPCommentsBySourceCodeFilename in SDK):
DELETE /code/cpp/comments/{dbName}/{filename}
This operation deletes the C++ comments related to the source code file with the given name `{filename}` in the project with the given name `{dbName}`.
Note that this operation only affects the intermediate representation of comments in the PKM, not comments in source code files.
**Insert or update Java source code comments** (REST API 🔐, see CodeApi.putJavaComments in SDK):
......@@ -506,34 +523,38 @@ This operation inserts the given Java comments from the request body into the pr
DELETE /code/java/comments/{dbName}
This operation deletes all the Java comments of the project with the given name `{dbName}`.
Note that this operation only affects the intermediate representation of comments in the PKM, not comments in source code files.
**Delete Java source code comments related to a Java source code file** (REST API 🔐, see CodeApi.deleteJavaCommentsBySourceCodeFilename in SDK):
DELETE /code/java/comments/{dbName}/{filename}
This operation deletes the Java comments related to the source code file with the given name `{filename}` in the project with the given name `{dbName}`.
Note that this operation only affects the intermediate representation of comments in the PKM, not comments in source code files.
**Delete all source code comments for any language** (REST API 🔐, see CodeApi.deleteSourceCodeComments in SDK):
DELETE /code/comments/{dbName}
This operation deletes all the source code comments of the project with the given name `{dbName}`.
Note that this operation only affects the intermediate representation of comments in the PKM, not comments in source code files.
**Delete source code comments for any language related to a source code file** (REST API 🔐, see CodeApi.deleteSourceCodeCommentsBySourceCodeFilename in SDK):
DELETE /code/comments/{dbName}/{filename}
This operation deletes the source code comments related to the source code file with the given name `{filename}` in the project with the given name `{dbName}`.
Note that this operation only affects the intermediate representation of comments in the PKM, not comments in source code files.
### 7.2.3 Annotations <a id="2.3"></a>
The schema for the source code annotations are available on the pkm-api gitlab repository:
The schemas for the source code annotations are available on the pkm-api gitlab repository:
* [for the C language](https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-acsl-schema.json) ([ACSL](https://frama-c.com/html/acsl.html))
* [for the C++ language](https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-acslpp-schema.json) ([ACSL++](https://frama-c.com/html/acsl.html))
* [for the Java language](https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/jml-schema.json) ([OpenJML](http://www.openjml.org))
The operations for source code annotations are the followings:
The operations for source code annotations are the following:
**Insert or update C source code annotations** (REST API 🔐, see CodeApi.putCAnnotations in SDK):
......@@ -632,7 +653,7 @@ The schema for the UML are available on the pkm-api gitlab repository:
The `name` property of UML classes or UML state machines uniquely identifies these artefacts.
The operations for UML are the followings:
The operations for UML are the following:
**Insert UML2 class diagrams** (REST API 🔐, see UMLApi.postUMLClassDiagrams in SDK):
......@@ -734,7 +755,7 @@ The schema for the graphical documentation of a class written in GSL is availabl
The `name` property of an ASFM uniquely identifies it.
The `class` and `object` properties of a class graphical documentation written in GSL uniquely identify it.
The operations for ASFM and the graphical documentation are the followings:
The operations for ASFM and the graphical documentation are the following:
**Insert documentation as ASFM** (REST API 🔐, see DocApi.postDocs in SDK):
......@@ -822,7 +843,7 @@ The `file` property of a compile command uniquely identifies it.
The schema for the compile commands is available on the [pkm-api gitlab repository](https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-compile-command-schema.json).
The operations for the compile commands are the followings:
The operations for the compile commands are the following:
**Insert compile commands** (REST API 🔐, see CompileCommandApi.postCompileCommands in SDK):
......@@ -880,7 +901,7 @@ The schema for CVE entries is available on the [pkm-api gitlab repository](https
The `CVE_data_meta.ID` property of a CVE entry uniquely identifies it.
The operations for CVE entries are the followings:
The operations for CVE entries are the following:
**Insert CVE entries** (REST API 🔐, see CVEApi.postCVEs in SDK):
......@@ -937,7 +958,7 @@ The schema for annotations is available on the [pkm-api gitlab repository](https
The `path` and `access` properties of an annotation uniquely identify it.
The `_id` property of an annotation that the PKM automatically assigns at insertion is an artefact identifier, which also uniquely identifies the annotation.
The operations for annotations are the followings:
The operations for annotations are the following:
**Insert annotations** (REST API 🔐, see AnnotationsApi.postAnnotations in SDK):
......@@ -997,7 +1018,7 @@ The schema for the traceability 2D matrix cell is available on the [pkm-api gitl
The `_id` property of a traceability matrix cell that the PKM automatically assigns at insertion, uniquely identifies the traceability matrix cell.
The operations for the traceability matrix are the followings:
The operations for the traceability matrix are the following:
**Insert Traceability Matrix cells** (REST API 🔐, see TraceabilityMatrixApi.postTraceabilityMatrix in SDK):
......@@ -1056,7 +1077,7 @@ The schema for logs is available on the [pkm-api gitlab repository](https://gitl
The `_id` property of a log that the PKM automatically assigns at insertion uniquely identifies the log.
The operations for logs are the followings:
The operations for logs are the following:
**Insert logs** (REST API 🔐, see LogApi.postLogs in SDK):
......@@ -1121,7 +1142,7 @@ The TESTAR settings are unique in a project.
The `_id` property of TESTAR test results or TESTAR state model that the PKM automatically assigns at insertion, uniquely identifies these artefacts.
The operations for TESTAR are the followings:
The operations for TESTAR are the following:
**Insert TESTAR settings** (REST API 🔐, see TESTARApi.postTESTARSettings in SDK):
......@@ -1139,7 +1160,7 @@ This operation inserts the given TESTAR settings from the request body into the
}
This operation inserts the given TESTAR settings from the request body into the project with the given name `{dbName}`, or update the existing TESTAR settings into the project with the given name `{dbName}` with the ones given from the request body..
This operation inserts the given TESTAR settings from the request body into the project with the given name `{dbName}`, or update the existing TESTAR settings into the project with the given name `{dbName}` with the ones given from the request body.
**Delete TESTAR settings** (REST API 🔐, see TESTARApi.deleteTESTARSettings in SDK):
......@@ -1224,7 +1245,7 @@ The schema for the reviews is available on the [pkm-api gitlab repository](https
The `reviewID` property of a review uniquely identifies the review.
The operations for the reviews are the followings:
The operations for the reviews are the following:
**Insert reviews** (REST API 🔐, see ReviewsApi.postReviews in SDK):
......@@ -1282,7 +1303,7 @@ The `toolID` property of a tool specification uniquely identifies it.
The `invocationID` property of a tool invocation uniquely identifies it.
The `id` property of a Methodology phase uniquely identifies it.
The operations for these collections are the followings:
The operations for these collections are the following:
**Insert tool specifications** (REST API 🔐, see ToolsApi.postTools in SDK):
......@@ -1405,7 +1426,7 @@ This operation inserts the given Methodology status from the request body into t
]
This operation inserts the given Methodology status from the request body into the project with the given name `{dbName}`, or update the existing Methodology status into the project with the given name `{dbName}` with the ones given from the request body..
This operation inserts the given Methodology status from the request body into the project with the given name `{dbName}`, or update the existing Methodology status into the project with the given name `{dbName}` with the ones given from the request body.
**Delete Methodology status** (REST API 🔐, see MethodologyApi.deleteMethodologyStatus in SDK):
......
......@@ -17,7 +17,17 @@
</div>
<div id="content">
<h1 id="querying-artefacts">9 Querying artefacts</h1>
<p>This chapter present all the queries that the PKM supports. In the PKM REST API, this corresponds to the GET requests. To lower the response footprint of GET requests, the PKM implements a windowing mechanism. Indeed, the GET requests that return a bare list have support for a 1D window while those returning a 2D matrix have support for a 2D window. There are some query parameters in the GET request (after the question mark in request URL) to configure that windowing mechanism.</p>
<p>This chapter present all the queries that the PKM supports.</p>
<p>In the PKM REST API, this corresponds to the HTTP GET requests. These operations can return one the following HTTP status codes:</p>
<ul>
<li>200: The operation is successful.</li>
<li>400: Bad request. The request has invalid request parameters in the URL.</li>
<li>401: The operation (labeled with a 🔐 symbol in this document) requires prior authentication (see Section 3).</li>
<li>403: Forbidden operation. The logged in user does not have sufficient rights to perform this operation.</li>
<li>404: Not found. The requested resource does not exist.</li>
<li>500: Internal server error. An error of this type is most likely due to a bug in the PKM server.</li>
</ul>
<p>To lower the response footprint of GET requests, the PKM implements a windowing mechanism. Indeed, the GET requests that return a bare list have support for a 1D window while those returning a 2D matrix have support for a 2D window. There are some query parameters in the GET request (after the question mark in request URL) to configure that windowing mechanism.</p>
<p>The 1D window query parameters are:</p>
<ul>
<li><code>skip</code>: starting index (i.e. number of elements to skip)</li>
......@@ -34,7 +44,7 @@
<h2 id="files">9.1 Files <a id="1"></a></h2>
<p><strong>Download a file</strong> (REST API 🔐, see IOApi.download in SDK):</p>
<pre><code>GET /io/{dbName}/{filename}?key=…</code></pre>
<p>This operation returns in the response body the requested file content. Unlike other PKM operations, the client shall pass the PKM access key in the query part of URL using the parameter named <code>key</code> . This operation is convenient for directly downloading a file from the PKM through HTTP(S) with the right content type (MIME type), so that a web browser, which has support for the content type, can seamlessly display it.</p>
<p>This operation returns in the response body the requested file content. Unlike other PKM operations, the client shall pass the PKM access key in the query part of URL using the parameter named <code>key</code>. This operation is convenient for directly downloading a file from the PKM through HTTP(S) with the right content type (MIME type), so that a web browser, which has support for the content type, can seamlessly display it.</p>
<p><strong>Get all files</strong> (REST API 🔐, see FilesApi.getFiles in SDK):</p>
<pre><code>GET /files/{dbName}</code></pre>
<p>This operation returns in the response body a list of all files in the project with the given name <code>{dbName}</code>.</p>
......
# 9 Querying artefacts
This chapter present all the queries that the PKM supports.
In the PKM REST API, this corresponds to the GET requests.
In the PKM REST API, this corresponds to the HTTP GET requests.
These operations can return one the following HTTP status codes:
* 200: The operation is successful.
* 400: Bad request. The request has invalid request parameters in the URL.
* 401: The operation (labeled with a 🔐 symbol in this document) requires prior authentication (see Section 3).
* 403: Forbidden operation. The logged in user does not have sufficient rights to perform this operation.
* 404: Not found. The requested resource does not exist.
* 500: Internal server error. An error of this type is most likely due to a bug in the PKM server.
To lower the response footprint of GET requests, the PKM implements a windowing mechanism.
Indeed, the GET requests that return a bare list have support for a 1D window while those returning a 2D matrix have support for a 2D window.
There are some query parameters in the GET request (after the question mark in request URL) to configure that windowing mechanism.
......@@ -27,7 +37,7 @@ Note that only the traceability matrix currently uses a 2D window.
GET /io/{dbName}/{filename}?key=…
This operation returns in the response body the requested file content.
Unlike other PKM operations, the client shall pass the PKM access key in the query part of URL using the parameter named `key` .
Unlike other PKM operations, the client shall pass the PKM access key in the query part of URL using the parameter named `key`.
This operation is convenient for directly downloading a file from the PKM through HTTP(S) with the right content type (MIME type), so that a web browser, which has support for the content type, can seamlessly display it.
**Get all files** (REST API 🔐, see FilesApi.getFiles in SDK):
......
......@@ -55,7 +55,7 @@ The white boxes show the paths of the endpoints.
The arrows outline the flow for generating new artefacts with parsers.
For a reason of limited space, the figure largely underestimates the generation flow of new artefacts when considering the whole DECODER Project tool-chain.
Note that there are some [OpenAPI](https://www.openapis.org/) specifications of the REST APIs available on the pkm-api gitlab repository for the followings:
Note that there are some [OpenAPI](https://www.openapis.org/) specifications of the REST APIs available on the pkm-api gitlab repository for the following:
* [PKM](https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-openapi.yaml)
* [Frama-C for PKM](https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/frama-c/api/frama-c-openapi.yaml)
......
......@@ -26,7 +26,7 @@ The PKM provides the following operations for supporting Git:
}
This runs the git command sequence passed in request body in the project with the given name `{dbName}`.
Commands `cd` or `chdir` in the command sequence allows changing the working directory to execute subsequent commands within a Git working tree.
Commands `cd` or `chdir` in the command sequence allow changing the working directory to execute subsequent commands within a Git working tree.
The operation returns in the response body a Git job which client can poll when in asynchronous mode (i.e. `asynchronous=true`) using the property `id` of the job as a job identifier.
When in asynchronous mode, the job is enqueued in a job queue.
The default behavior is to run jobs synchronously.
......
......@@ -2,6 +2,18 @@
This chapter describes the operations that the PKM provides to manage documents, i.e. inserting, updating and deleting documents.
In the PKM REST API, these operations correspond to the HTTP POST, PUT, and DELETE requests.
These requests can return one the following HTTP status codes:
* 200: The operation is successful.
* 201: The PKM created a new resource.
* 400: Bad request. The request has invalid request parameters in the URL, or the format of the request body is malformed.
In the latter case, it means that the JSON validation of the input fails against the JSON schema.
* 401: The operation (labeled with a 🔐 symbol in this document) requires prior authentication (see Section 3).
* 403: Forbidden operation. The logged in user does not have sufficient rights to perform this operation.
* 404: Not found; the requested resource does not exist.
* 500: Internal server error. An error of this type is most likely due to a bug in the PKM server.
## 7.1 Files <a id="1"></a>
The PKM REST API models a file as a JSON object with the following properties:
......@@ -323,13 +335,13 @@ The following subsections present the operations of the PKM API, which are inten
### 7.2.1 Abstract Syntax Trees (ASTs) <a id="2.1"></a>
The schema for the source code ASTs are available on the pkm-api gitlab repository:
The schemas for the source code ASTs are available on the pkm-api gitlab repository:
* [for the C language](https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-c-source-code-schema.json)
* [for the C++ language](https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-cpp-source-code-schema.json)
* [for the Java language](https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-java-source-code-schema.json)
The operations for ASTs are the followings:
The operations for ASTs are the following:
**Insert or update C source code ASTs** (REST API 🔐, see CodeApi.putCSourceCodes in SDK):
......@@ -431,12 +443,13 @@ This operation deletes the source code ASTs related to the source code file with
### 7.2.2 Comments <a id="2.2"></a>
The schema for the source code comments are available on the pkm-api gitlab repository:
The schemas for the source code comments are available on the pkm-api gitlab repository:
* [for the C language](https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-c-comments-schema.json)
* [for the C++ language](https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-cpp-comments-schema.json)
* [for the Java language](https://gitlab.ow2.org/decoder/pkm-api/-/blob/master/api/pkm-java-comments-schema.json)
The operations for source code comments are the followings:
The operations for source code comments are the following: