3. API Description ================== This section describes the available API endpoints provided by the Semantic Ethical Glass Box (SEGB), including their usage, expected inputs, and response formats. Authentication and Permissions ------------------------------ The SEGB API uses **Bearer Tokens** for authentication and authorization. Each endpoint requires a specific role to access it. The roles are defined as follows: - **Auditor**: Can read the graph and experiment data. - **Logger**: Can log data to the SEGB. - **Admin**: Has full access to all endpoints, including deleting the graph and accessing the history. These must be included as information at token generation time. The SEGB server will validate the token and check the permissions associated with it before processing the request. A token can be defined with several roles and the server will check the permissions for each endpoint. It means that a auditor/logger token can be generated. .. note:: Tokens must be generated manually by a SEGB admin (who knows the secret) using `token_generator_script.py` and are unique to each user. The tokens are valid for a limited time and should be kept secure. The server will not accept expired or invalid tokens. Additionally, tokens should be refreshed periodically to maintain security. Tokens must be included in the `Authorization` header as follows: ``Authorization: Bearer `` If the server is secured, unauthorized access will result in the following status codes: - `401 Unauthorized`: Invalid token. - `403 Forbidden`: Token provided but insufficient permissions or no token provided. 3.1. GET / ---------- **Description:** The root endpoint serves as a redirect to the `/docs` playground, providing an entry point for exploring the API documentation. **Request Details:** - **URL:** `/` - **Method:** `GET` **Response Codes:** .. list-table:: :widths: 20 80 :header-rows: 1 * - Status Code - Description * - ``200 OK`` - The server is operational and redirects to the `/docs` playground for API exploration. 3.2. GET /health ---------- **Description:** Health check endpoint to verify that the SEGB server is running. **Request Details:** - **URL:** `/health` - **Method:** `GET` **Response Codes:** .. list-table:: :widths: 20 80 :header-rows: 1 * - Status Code - Description * - ``200 OK`` - The server is running and returns the message: "The SEGB is working". 3.3. POST /log -------------- **Description:** This endpoint receives data in **Turtle (TTL)** format, converts it into **JSON-LD**, and stores it in the database. The TTL payload may include one or multiple RDF triples. **Request Details:** - **URL:** `/log` - **Method:** `POST` - **Required Headers:** - ``Content-Type: text/turtle; encoding=utf-8`` - ``Authorization: Bearer `` - **Request Body:** - A valid RDF document in **Turtle (TTL)** format. **Response Codes:** .. list-table:: :widths: 20 80 :header-rows: 1 * - Status Code - Description * - ``201 Created`` - The data was successfully received and stored. * - ``403 Forbidden`` - Insufficient permissions (e.g., using a Auditor Token). * - ``422 Unprocessable Entity`` - The request contained invalid or malformed data. 3.4. GET /log ------------- **Description:** Retrieve detailed information about a specific log entry. **Request Details:** - **URL:** `/log` - **Method:** `GET` - **Required Headers:** - ``Authorization: Bearer `` - **Query Parameters:** - ``log_id``: The ID of the log to retrieve. **Response Codes:** .. list-table:: :widths: 20 80 :header-rows: 1 * - Status Code - Description * - ``200 OK`` - Returns the log details in JSON format. * - ``400 Bad Request`` - Missing or invalid `log_id` parameter. * - ``403 Forbidden`` - Insufficient permissions (e.g., using a Logger Token). * - ``404 Not Found`` - The specified log was not found. 3.5. GET /graph --------------- **Description:** Retrieve the entire graph stored in the SEGB in **Turtle (TTL)** format. **Request Details:** - **URL:** `/graph` - **Method:** `GET` - **Required Headers:** - ``Authorization: Bearer `` **Response Codes:** .. list-table:: :widths: 20 80 :header-rows: 1 * - Status Code - Description * - ``200 OK`` - Successfully returns the graph in **Turtle (TTL)** format. * - ``204 No Content`` - The graph is empty. * - ``403 Forbidden`` - Insufficient permissions (e.g., using a Logger Token). 3.6. DELETE /graph ------------------ **Description:** Delete the entire graph stored in the SEGB. **Request Details:** - **URL:** `/graph` - **Method:** `DELETE` - **Required Headers:** - ``Authorization: Bearer `` **Response Codes:** .. list-table:: :widths: 20 80 :header-rows: 1 * - Status Code - Description * - ``200 OK`` - The graph was successfully deleted. * - ``204 No Content`` - The graph was already empty. * - ``403 Forbidden`` - Insufficient permissions (e.g., using a Auditor Token). 3.7. GET /experiments --------------------- **Description:** Retrieve a list of all experiments registered or information about a specific experiment and its associated activities (based on parameters). **Request Details:** - **URL:** `/experiments` - **Method:** `GET` - **Required Headers:** - ``Authorization: Bearer `` - **Query Parameters:** - Retrieving a list of all experiments can be done by providing no parameters. - **Important:** If no parameters are provided, the endpoint will return all experiment URIs registered in the SEGB in JSON format. - Example without parameters: - **Request:** .. code-block:: text GET /experiments HTTP/1.1 Host: http://example.com/experiments Authorization: Bearer - **Response:** .. code-block:: json [ "http://www.gsi.upm.es/ontologies/amor/experiments/execution/ns#exp1", "http://www.gsi.upm.es/ontologies/amor/experiments/execution/ns#exp2" ] - Retrieving information about a specific experiment can be done in two ways: - **Note:** Any of the following alternatives can be used to specify the experiment in query parameters. - Option 1: - ``uri``: Complete URI of the experiment (e.g., `namespace#experiment_id`). - **Important:** If `uri` is provided, the `namespace` and `experiment_id` parameters will be ignored. - **Recommendation:** When using Python's `requests` library, use the `params` argument to ensure proper encoding of the `#` character as `%23`. For example: .. code-block:: python import requests url = "http://example.com/experiments" params = {"uri": "http://www.gsi.upm.es/ontologies/amor/experiments/execution/ns#exp1"} headers = {"Authorization": "Bearer "} response = requests.get(url, params=params, headers=headers) print(response.url) # The URL will automatically encode # as %23 - **Note for query parameter:** The `uri` parameter contains # character is not allowed in a query parameter, it must be encoded as `%23` if it is included in the URI. This is not required if the `params` argument is used, as in the previous example. For example: .. code-block:: text /experiments?uri=http://www.gsi.upm.es/ontologies/amor/experiments/execution/ns%23exp1 - Option 2: - ``namespace``: The namespace of the experiment. - ``experiment_id``: The ID of the experiment. - **Recommendation:** When using Python's `requests` library, use the `params` argument to ensure proper encoding of the `#` character as `%23`. For example: .. code-block:: python import requests url = "http://example.com/experiments" params = {"namespace": "http://www.gsi.upm.es/ontologies/amor/experiments/execution/ns", "experiment_id": "exp1"} headers = {"Authorization": "Bearer "} response = requests.get(url, params=params, headers=headers) print(response.url) # The URL will automatically encode # as %23 - The following examples are valid: .. code-block:: text /experiments?namespace=http://www.gsi.upm.es/ontologies/amor/experiments/execution/ns&experiment_id=exp1 .. code-block:: text /experiments?namespace=http://www.gsi.upm.es/ontologies/amor/experiments/execution/ns%23&experiment_id=exp1 **Response Codes:** .. list-table:: :widths: 20 80 :header-rows: 1 * - Status Code - Description * - ``200 OK`` - Returns the experiment details in **Turtle (TTL)** format (if `uri` is provided) or JSON format (if `namespace` and `experiment_id` are provided). If not, returns a list of all experiment URIs registered in the SEGB. * - ``204 No Content`` - No experiments found. * - ``403 Forbidden`` - Insufficient permissions (e.g., using a Logger Token). * - ``404 Not Found`` - The specified experiment was not found. * - ``422 Unprocessable Entity`` - Missing required parameters (e.g., `namespace` or `experiment_id`) or **Invalid URI format**. The URI must be a valid IRI (Internationalized Resource Identifier #) and should not contain spaces or special characters that are not allowed in IRIs. The URI must also be properly encoded if it contains reserved characters. 3.8. GET /history ------------------ **Description:** Retrieve the history of all logged actions in the SEGB. **Request Details:** - **URL:** `/history` - **Method:** `GET` - **Required Headers:** - ``Authorization: Bearer `` **Response Codes:** .. list-table:: :widths: 20 80 :header-rows: 1 * - Status Code - Description * - ``200 OK`` - Returns the history in JSON format. * - ``204 No Content`` - No history found. * - ``403 Forbidden`` - Insufficient permissions (e.g., using a Logger Token). 3.9. GET /query --------------- **Description:** Execute a SPARQL query on the graph. **(Not implemented yet)** **Request Details:** - **URL:** `/query` - **Method:** `GET` - **Required Headers:** - ``Authorization: Bearer `` **Response Codes:** .. list-table:: :widths: 20 80 :header-rows: 1 * - Status Code - Description * - ``403 Forbidden`` - Insufficient permissions (e.g., using a Auditor or Logger Token). * - ``501 Not Implemented`` - This endpoint is not yet implemented. 3.10. GET /docs -------------- **Description:** Access the OpenAPI playground for exploring and testing the SEGB API **Request Details:** - **URL:** `/docs` - **Method:** `GET` **Response Codes:** .. list-table:: :widths: 20 80 :header-rows: 1 * - Status Code - Description * - ``200 OK`` - Successfully loads the OpenAPI playground.