Merge pull request #58 from LibreSign/chore/reorganize-developer-content-structure

Chore/reorganize developer content structure

Author: vitormattos

developer_manual/api/guide-api.rst

@@ -0,0 +1,91 @@
+API Usage
+=========
+
+LibreSign exposes endpoints via **REST** and **OCS (Open Collaboration Services)**.
+
+By default, all requests require authentication (Basic Auth, App Password, OIDC, or session cookies) and return JSON responses.
+
+Base URLs
+---------
+
+- **OCS**: ``https://cloud.example.com/ocs/v2.php/apps/libresign/api/v1/``
+
+**Versioning**: breaking changes result in a new major version (e.g., ``v2``).
+
+Authentication
+--------------
+
+Supported methods:
+
+- **Basic Auth** (App Password or Username/Password)
+- **OIDC Access Token** (``Authorization: Bearer <ACCESS_TOKEN>``)
+- **Session cookies** (for non-OCS endpoints, may require CSRF token)
+
+.. note::
+   Prefer using an **App Password** for Basic Auth. For OIDC, use **Access Tokens**.
+
+.. note::
+    Use an application password instead of your regular password.  
+    Besides improved security, this also improves performance.  
+
+    To configure one:
+
+    - log into the Nextcloud Web interface
+    - click on your avatar,  
+    - select *Personal settings*, then *Security*.
+    - At the bottom of the page you can create an app password, which can also be revoked later without changing your main password.
+
+Basic Auth (App Password)
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+    curl -sS -u "username:app-password" \
+      -H "Accept: application/json" \
+      -H "OCS-APIRequest: true" \
+      "https://cloud.example.com/ocs/v2.php/apps/libresign/api/v1/..."
+
+OIDC (Access Token)
+~~~~~~~~~~~~~~~~~~~
+
+`Read more <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization/>`__
+
+.. code-block:: bash
+
+    curl -sS \
+      -H "Authorization: Bearer ${ACCESS_TOKEN}" \
+      -H "Accept: application/json" \
+      -H "OCS-APIRequest: true" \
+      "https://cloud.example.com/ocs/v2.php/apps/libresign/api/v1/..."
+
+Clients
+-------
+
+- Requests with a body (:code:`POST`, :code:`PUT`, :code:`PATCH`) must include ``Content-Type: application/json``.
+
+CURL
+~~~~
+
+All OCS requests can be tested with :code:`curl` by specifying the request method (:code:`GET`, :code:`POST`, :code:`PATCH`, etc.) and the required headers.
+
+Example:
+
+.. code-block:: bash
+
+    curl --request POST \
+        --url http://cloud.example.com/apps/libresign/api/v1/request-signature \
+        --header 'Authorization: Basic <base64-credentials>' \
+        --header 'Content-Type: application/json' \
+        --data '{
+            "file": {
+                "url": "https://example.com/test.pdf"
+            },
+            "status": 0,
+            "name": "Contract",
+            "users": [
+                {
+                    "email": "[email protected]"
+                    "displayName": "User Name"
+                }
+            ]
+        }'

developer_manual/api/index.rst

@@ -0,0 +1,9 @@
+=================
+API Documentation
+=================
+
+.. toctree::
+    :maxdepth: 2
+
+    guide-api
+    openapi

developer_manual/api.rst developer_manual/api/openapi.rstdeveloper_manual/api.rst renamed to developer_manual/api/openapi.rst

@@ -1,5 +1,5 @@
-API
-===
+OCS OpenAPI
+===========
 
 .. raw:: html
 

developer_manual/code-of-conduct.rst

@@ -3,7 +3,7 @@ Branch policies
 
 This document describes the branching model used in LibreSign and how contributions should be targeted.
 
-Branch Names
+Branch names
 ------------
 
 Main
@@ -42,7 +42,7 @@ Stable branches maintain release lines compatible with a specific **Nextcloud Se
         In LibreSign, ``min-version`` and ``max-version`` are always the same number.  
         This number is the MAJOR version of the compatible Nextcloud Server.
 
-Target Branches for Contributions
+Target branches for contributions
 ---------------------------------
 
 -   **New features / improvements**:
@@ -61,18 +61,18 @@ Target Branches for Contributions
     -   Create a branch from that stable branch.
     -   Open a PR to the same stable branch.
 
-Bugfixes and Backports
+Bugfixes and backports
 ----------------------
 If a bug fix also needs to be applied to an older release line, it must be **backported**.  
 Backporting means applying the same change to another branch (Git calls this *cherry-picking*).
 
-Automatic Backport
+Automatic backport
 ^^^^^^^^^^^^^^^^^^
 If the cherry-pick applies cleanly and only small conflicts need to be resolved, the `backport bot <https://github.com/nextcloud/backportbot>`_ can be used.
 
 See the `bot usage <https://github.com/nextcloud/backportbot#usage>`_ for available commands.
 
-Manual Backport
+Manual backport
 ^^^^^^^^^^^^^^^
 For more complex changes, the backport must be done manually:
 
@@ -93,6 +93,6 @@ For more complex changes, the backport must be done manually:
 
     # Open a pull request for the backport
 
-Creating Branch
+Creating branch
 ---------------
 Follow the convention of naming branches as ``feature/description`` or ``bugfix/description``.