From a6750c5837a17afdede34f9395e3c1c768e012bd Mon Sep 17 00:00:00 2001 From: TharcioCBM Date: Mon, 8 Jan 2024 14:39:37 -0300 Subject: [PATCH 01/10] doc: adding flasgger library to build OpenAPI-Specification --- requirements.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/requirements.txt b/requirements.txt index ca4a874..cc9203b 100644 --- a/requirements.txt +++ b/requirements.txt @@ -28,6 +28,8 @@ gunicorn pytest~=7.1.3 # requests==2.28.1 pytest-env==0.6.2 +# docs +flasgger==0.9.5 # dark dark-gateway==0.1.0 From 731d1da688140842276fa65fccfa13af95db6964 Mon Sep 17 00:00:00 2001 From: TharcioCBM Date: Mon, 8 Jan 2024 15:39:18 -0300 Subject: [PATCH 02/10] doc: flagger version modification --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index cc9203b..0731d8d 100644 --- a/requirements.txt +++ b/requirements.txt @@ -29,7 +29,7 @@ pytest~=7.1.3 # requests==2.28.1 pytest-env==0.6.2 # docs -flasgger==0.9.5 +flasgger==0.9.7b2 # dark dark-gateway==0.1.0 From 1564234ffc483b4c33e597e6e89a72b54b12c492 Mon Sep 17 00:00:00 2001 From: TharcioCBM Date: Mon, 8 Jan 2024 15:40:45 -0300 Subject: [PATCH 03/10] feat: add new non_auth_routs to the auth_middleware --- app/util/auth_middleware.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/util/auth_middleware.py b/app/util/auth_middleware.py index 248987a..1109959 100644 --- a/app/util/auth_middleware.py +++ b/app/util/auth_middleware.py @@ -13,7 +13,7 @@ def authentication_middleware(): token = request.headers.get('Authorization') - non_auth_routes = ['/user/login', '/core/get'] + non_auth_routes = ['/apidocs','/','/user/login', '/core/get'] if request.path in non_auth_routes: return From b486f5ab58d4ef9a319d02764f38187e2d64d29f Mon Sep 17 00:00:00 2001 From: TharcioCBM Date: Mon, 8 Jan 2024 15:43:23 -0300 Subject: [PATCH 04/10] feat: initial implementation of the swagger-ui and OpenAPI-Specification --- app/instance_app.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/app/instance_app.py b/app/instance_app.py index 8d44add..22ebb78 100644 --- a/app/instance_app.py +++ b/app/instance_app.py @@ -1,6 +1,6 @@ import os from flask import Flask - +from flasgger import Swagger from database.variables_database import ConfigVariables from model import configure as config_db from serealize import configure as config_ma @@ -32,5 +32,6 @@ def create_app(): Migrate(app, app.db) JWTManager(app) - + Swagger(app) + return app From 8e6d3a71589264bb5b12f3e016e2d30003731a1c Mon Sep 17 00:00:00 2001 From: TharcioCBM Date: Wed, 24 Jan 2024 17:16:13 -0300 Subject: [PATCH 05/10] feat: adding pid check function inside add_general method --- app/api/core_api.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/app/api/core_api.py b/app/api/core_api.py index b3fc48d..756633c 100644 --- a/app/api/core_api.py +++ b/app/api/core_api.py @@ -175,6 +175,11 @@ def set_general(ark_id): def add_general(ark_id): pid = None + if ark_id.startswith("0x"): + pid = dark_map.get_pid_by_hash(ark_id) + else: + pid = dark_map.get_pid_by_ark(ark_id) + if request.is_json: data = request.get_json() if len(data) == 0: @@ -201,3 +206,4 @@ def add_general(ark_id): return add_external_pid(ark_id, pid) return make_response(error_response(action="add", error_message="Invalid or missing data in the request. Please check your input and try again.", error_code=400, pid=pid)) + From 08a65a426f157c21d7631f74db3b8f7617876831 Mon Sep 17 00:00:00 2001 From: TharcioCBM Date: Wed, 24 Jan 2024 17:19:14 -0300 Subject: [PATCH 06/10] feat: adding swagger routes in non_auth_routes (auth_middleware) --- app/util/auth_middleware.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/app/util/auth_middleware.py b/app/util/auth_middleware.py index 1109959..5d2a7af 100644 --- a/app/util/auth_middleware.py +++ b/app/util/auth_middleware.py @@ -13,11 +13,12 @@ def authentication_middleware(): token = request.headers.get('Authorization') - non_auth_routes = ['/apidocs','/','/user/login', '/core/get'] - + non_auth_routes = ['/','/user/login', '/core/get','/static/swagger.json'] + if request.path in non_auth_routes: return - + if request.endpoint == 'swagger' or request.path.startswith('/swagger'): + return try: jwt_required()(lambda: None)() From 364e7b97048e4cfa0ecaf29aa025b1beec57c56c Mon Sep 17 00:00:00 2001 From: TharcioCBM Date: Thu, 8 Feb 2024 16:16:28 -0300 Subject: [PATCH 07/10] doc: Replacement of the flasgger extension with the flask-swagger-ui extension version 4.11.1. --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 0731d8d..99e7c94 100644 --- a/requirements.txt +++ b/requirements.txt @@ -29,7 +29,7 @@ pytest~=7.1.3 # requests==2.28.1 pytest-env==0.6.2 # docs -flasgger==0.9.7b2 +flask-swagger-ui==4.11.1 # dark dark-gateway==0.1.0 From ebc110fe2907a38b947b9dd8c7bb12b1bd4118e8 Mon Sep 17 00:00:00 2001 From: TharcioCBM Date: Thu, 8 Feb 2024 16:19:41 -0300 Subject: [PATCH 08/10] feat: settings to implement the new swagger-ui feature --- app/api_server.py | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/app/api_server.py b/app/api_server.py index 7ed646f..bcbf28e 100644 --- a/app/api_server.py +++ b/app/api_server.py @@ -1,14 +1,13 @@ import sys import os - from flask import Flask, jsonify, render_template, send_file, abort # from flask import render_template, request, Flask, g, send_from_directory, abort, jsonify from instance_app import create_app from api.query_api import queries_blueprint from api.core_api import core_api_blueprint -from api.user_api import user_api_blueprint - +from api.user_api import user_api_blueprint from util.auth_middleware import authentication_middleware +from flask_swagger_ui import get_swaggerui_blueprint app = create_app() @@ -16,6 +15,16 @@ app.config['JSON_AS_ASCII'] = False # utf8 app.config['JSON_SORT_KEYS'] = False # prevent sorting json +# swagger configs +SWAGGER_URL = '/swagger' +API_URL = '/static/swagger.json' +SWAGGER_BLUEPRINT = get_swaggerui_blueprint( + SWAGGER_URL, + API_URL, + config={ + 'app_name' : "hiperdrive API" + } +) app.before_request(authentication_middleware) @@ -23,13 +32,16 @@ app.register_blueprint(queries_blueprint) app.register_blueprint(core_api_blueprint) app.register_blueprint(user_api_blueprint) - +app.register_blueprint(SWAGGER_BLUEPRINT, url_prefix = SWAGGER_URL) @app.route('/') + + def index(): return render_template('home.html') + if __name__ == "__main__": # TODO: RECUPERAR A PORTA DO ENV app.run(host='0.0.0.0', port=8080) From 8e07e7cbe15c0e37802dd07dba088469a594ef1d Mon Sep 17 00:00:00 2001 From: TharcioCBM Date: Thu, 8 Feb 2024 16:23:24 -0300 Subject: [PATCH 09/10] feat: removal of unused code after replacing the swagger extension --- app/instance_app.py | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/app/instance_app.py b/app/instance_app.py index 22ebb78..06e8e98 100644 --- a/app/instance_app.py +++ b/app/instance_app.py @@ -1,25 +1,24 @@ import os from flask import Flask -from flasgger import Swagger from database.variables_database import ConfigVariables from model import configure as config_db from serealize import configure as config_ma - from flask_migrate import Migrate from flask_jwt_extended import JWTManager + # TODO: Definir melhor # PROJECT_ROOT = os.path.dirname(os.path.dirname(__file__)) PROJECT_ROOT = '.' config_variables = ConfigVariables() - # templates template_dir = os.path.join(PROJECT_ROOT, 'templates') def create_app(): + app = Flask(__name__, template_folder=template_dir) app.config["SQLALCHEMY_DATABASE_URI"] = f"postgresql://{os.environ['DB_USER']}:{os.environ['DB_PASS']}@{os.environ['DB_HOST']}:{os.environ['DB_PORT']}/{os.environ['DB_NAME']}" @@ -30,8 +29,7 @@ def create_app(): config_ma(app) Migrate(app, app.db) - JWTManager(app) - Swagger(app) + return app From 54ba8bca61f5cce9c159bf15a1071d50c3b8c464 Mon Sep 17 00:00:00 2001 From: TharcioCBM Date: Thu, 8 Feb 2024 16:35:36 -0300 Subject: [PATCH 10/10] doc: json file containing the description in openAPI format of the hyperdrive and which can be read in the swagger-ui extension --- app/static/swagger.json | 1043 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 1043 insertions(+) create mode 100644 app/static/swagger.json diff --git a/app/static/swagger.json b/app/static/swagger.json new file mode 100644 index 0000000..454bebf --- /dev/null +++ b/app/static/swagger.json @@ -0,0 +1,1043 @@ +{ + "openapi": "3.0.0", + "info": { + "description": "Hyperdrive is responsible for intermediating access to the Blockchain through its routes access which are documented below.", + "version": "1.0.0", + "title": "Hyperdrive API Documentation", + "license": { + "name": "GNU General Public License v3.0", + "url": "https://github.com/dark-pid/hyperdrive/blob/main/LICENSE" + } + }, + "paths": { + "/user/login" :{ + "description": "Login User: authenticates the user using their data in the database.", + "summary": "Through this method the user authenticates", + "post" :{ + "description": "Through the method, the user can send their credentials that will be used to carry out authentication", + "requestBody":{ + "$ref": "#/components/requestBodies/login" + }, + "responses": { + "200":{ + "description": "the success response means that the user will receive the authentication token to access the other API methods", + "content": { + "application/json":{ + "schema":{ + "description": "", + "allOf": [ + { + "$ref": "#/components/schemas/Action" + }, + { + "$ref": "#/components/schemas/Status" + }, + { + "type": "object", + "properties": { + "api_auth_key":{ + "description": "this parameter refers to the JWT access token that authorizes the user to access the Hyperdrive API methods. It is returned as a string and is available in synchronous and asynchronous modes.", + "type": "string" + } + } + } + ] + }, + "example":{ + "action": "authenticate", + "status": "executed", + "api_auth_key":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmcmVzaCI6ZmFsc2UsImlhdCI6MTcwNjExNzY0MCwianRpIjoiMDViNWNhNjAtYWJlZC00NDgxLWI3NGUtZDRmM2MwNjI1MTMxIiwidHlwZSI6ImFjY2VzcyIsInN1YiI6MSwibmJmIjoxNzA2MTE3NjQwLCJleHAiOjE3MDYxMzkyNDB9.Ahg0ofJFeXZMylBMU_ADSk2OCaS1L974wZqWeIzC18M" + } + } + } + }, + "400":{ + "description": "standard error response in json format", + "content": { + "application/json":{ + "schema":{ + "$ref": "#/components/schemas/error_response" + }, + "examples":{ + "exemple1":{ + "description": "error message triggered when the user submits an invalid email or password", + "value":{ + "action": "authenticate", + "status": "Rejected", + "error_code": 400, + "error_message": "invalid credentials" + } + }, + "exemple2":{ + "description": "error message triggered when the user does not send any information to the request body", + "value":{ + "action": "authenticate", + "status": "Rejected", + "error_code": 400, + "error_message": "No parameter has been passed" + } + }, + "exemple3":{ + "description": "error message triggered when the user does not send one of the information in the request body", + "value":{ + "action": "authenticate", + "status": "Rejected", + "error_code": 400, + "error_message": "Unspecified email or password" + } + } + } + } + } + } + } + } + }, + "/core/new":{ + "description": "the path that is used to generate a new pid", + "summary": "request a PID to the hyperdrive", + "post":{ + "description": "using this method it is possible to generate a new draft pid", + "security": [ + { + "bearerAuth":[] + } + ], + "parameters": [ + ], + "responses": { + "200":{ + "description": "the success response in json format containing a draft pid and the your hash index", + "content": { + "application/json":{ + "schema":{ + "description": "", + "allOf": [ + { + "$ref": "#/components/schemas/Action" + }, + { + "$ref": "#/components/schemas/Status" + }, + { + "$ref": "#/components/schemas/Pid_hash_index" + }, + { + "$ref": "#/components/schemas/Pid" + } + ] + }, + "example":{ + "action": "create_pid", + "pid": "8033/fkwff30000000000026", + "pid_hash_index": "0xc764a3c06b1f4d8f723b466541b9cfc66a88ba3ca5a02ee090e2396e065f5d1a", + "status": "executed" + } + } + + } + }, + "500":{ + "description": "internal error in the blockchain ", + "content": { + "application/json":{ + "schema":{ + "$ref": "#/components/schemas/error_response" + }, + "example":{ + "error": { + "message": "block_chain_error_message", + "error_code": 500, + "action": "create_pid", + "status": "Unable to create a new PID" + } + } + } + } + } + } + }, + "get":{ + "summary": "", + "description": "", + "security": [ + { + "bearerAuth":[] + } + ], + "responses": { + "200":{ + "description": "", + "content": { + "application/json":{ + "schema":{ + + } + } + + } + }, + "400":{ + "description": "", + "content": { + "application/json":{ + "schema":{ + + } + } + } + } + } + } + }, + "/core/add/{dark_id}":{ + "summary": "add an attribute to PID", + "description": "route used to add new attributes to an already created pid", + "post":{ + "description": "the post method is used to add new attributes to a pid, using a body in json format it is possible to submit one of the following keys: external_url or external pid", + "requestBody":{ + "$ref": "#/components/requestBodies/add_external_attributes" + }, + "parameters": [ + { + "$ref": "#/components/parameters/dark_id" + } + ], + "security": [ + { + "bearerAuth":[] + } + ], + "responses": { + "200":{ + "description": "json format success response containing the request components, alternating depending on the hyperdrive operating mode and the parameter submitted by the user", + "content": { + "application/json":{ + "schema":{ + "oneOf": [ + { + "$ref": "#/components/schemas/async_success_response" + }, + { + "$ref": "#/components/schemas/sync_success_response" + } + ] + }, + "examples": { + "Example1":{ + "$ref": "#/components/examples/add_external_url_async_response_exemple" + }, + "Example2":{ + "$ref": "#/components/examples/add_external_url_sync_response_exemple" + }, + "Exemple3":{ + "description": "", + "value":{ + "action": "add_external_pid", + "hyperdrive_op_mode": "async", + "parameter": { + "external_pid": "doi:/116.jdakt.7892", + "pid": "8033/fkwff3000000000005k" + }, + "pid": "8033/fkwff3000000000005k", + "pid_hash_index": "0xd454201ebc0d81a8b060d766d4e9f0556d020b4412e32b282e29d3efb43a9c9f", + "status": "queued", + "transaction_hash": "0xe2d0fe1b3c583af4d1abf88dadca3200cef75a44c5fced0fa8c69385220a699b" + } + }, + "Exemple4":{ + "description": "", + "value":{ + "action": "add_external_pid", + "hyperdrive_op_mode": "sync", + "parameter": { + "external_pid": "doi:/116.jdakt.7892", + "pid": "8033/fkwff3000000000005k" + }, + "pid": "8033/fkwff3000000000005k", + "pid_hash_index": "0xd454201ebc0d81a8b060d766d4e9f0556d020b4412e32b282e29d3efb43a9c9f", + "status": "executed" + } + } + } + } + } + }, + "400":{ + "description": "json format error response containing the request components, alternating depending on the parameter submitted by the user", + "content": { + "application/json":{ + "schema":{ + "oneOf": [ + { + "$ref": "#/components/schemas/generic_with_parameter_error_response" + }, + { + "$ref": "#/components/schemas/generic_without_parameter_error_response" + } + ] + }, + "examples":{ + "Example1":{ + "description": "", + "value":{ + "error": { + "action": "add", + "error_code": 400, + "message": "Invalid or missing data in the request. Please check your input and try again.", + "pid": "8033/fkwff3000000000005k", + "pid_hash_index": "0xd454201ebc0d81a8b060d766d4e9f0556d020b4412e32b282e29d3efb43a9c9f", + "status": "rejected" + } + } + }, + "Example2":{ + "description": "", + "value":{ + "error": { + "action": "add", + "error_code": 400, + "message": "No parameter has been passed", + "pid": "8033/fkwff3000000000005k", + "pid_hash_index": "0xd454201ebc0d81a8b060d766d4e9f0556d020b4412e32b282e29d3efb43a9c9f", + "status": "rejected" + } + } + } + } + } + } + }, + "500":{ + "description": "blockchain internal error response", + "content": { + "application/json":{ + "schema":{ + "oneOf": [ + { + "$ref": "#/components/schemas/generic_with_parameter_error_response" + }, + { + "$ref": "#/components/schemas/generic_without_parameter_error_response" + } + ] + }, + "examples": { + "Example1":{ + "description": "", + "value":{ + "error": { + "action": "add", + "error_code": 500, + "message": "Unable to execute multiple operations considering the Hyperdriver Synchronized Mode.", + "pid": "8033/fkwff3000000000005k", + "pid_hash_index": "0xd454201ebc0d81a8b060d766d4e9f0556d020b4412e32b282e29d3efb43a9c9f", + "status": "rejected" + } + } + }, + "Example2":{ + "description": "", + "value":{ + "error": "list index out of range" + } + } + } + } + } + }, + "501":{ + "description": "", + "content": { + "application/json":{ + "schema":{ + "$ref": "#/components/schemas/generic_with_parameter_error_response" + } + } + } + } + } + } + }, + "/core/set/{dark_id}":{ + "summary": "set PID attribute", + "description": "route used to set attributes to an already created pid", + "post":{ + "description": "the post method accepts a json body with only one of the following keys: external_url or payload", + "requestBody":{ + "$ref": "#/components/requestBodies/set_external_attributes" + }, + "parameters": [ + { + "$ref": "#/components/parameters/dark_id" + } + ], + "security": [ + { + "bearerAuth":[] + } + ], + "responses": { + "200":{ + "description": "json format success response containing the request components, alternating depending on the hyperdrive operating mode and the parameter submitted by the user", + "content": { + "application/json":{ + "schema":{ + "oneOf": [ + { + "$ref": "#/components/schemas/async_success_response" + }, + { + "$ref": "#/components/schemas/sync_success_response" + } + ] + }, + "examples": { + "Example1":{ + "description": "", + "value":{ + "action": "set_payload", + "hyperdrive_op_mode": "async", + "parameter": { + "payload": { + "X": "Y" + }, + "pid": "8033/fkwff3000000000005k" + }, + "pid": "8033/fkwff3000000000005k", + "pid_hash_index": "0xd454201ebc0d81a8b060d766d4e9f0556d020b4412e32b282e29d3efb43a9c9f", + "status": "queued", + "transaction_hash": "0xfa3565d4ce4b2b21428824dad9bc8598a4bccc2580c219d7f0f0bed39b7cec58" + } + }, + "Example2":{ + "description": "", + "value":{ + "action": "set_payload", + "hyperdrive_op_mode": "sync", + "parameter": { + "payload": { + "X": "Y" + }, + "pid": "8033/fkwff3000000000005k" + }, + "pid": "8033/fkwff3000000000005k", + "pid_hash_index": "0xd454201ebc0d81a8b060d766d4e9f0556d020b4412e32b282e29d3efb43a9c9f", + "status": "executed" + } + } + } + } + } + }, + "400":{ + "description": "json format error response containing the request components, alternating depending on the parameter submitted by the user", + "content": { + "application/json":{ + "schema":{ + "oneOf": [ + { + "$ref": "#/components/schemas/generic_with_parameter_error_response" + }, + { + "$ref": "#/components/schemas/generic_without_parameter_error_response" + } + ] + }, + "examples": { + "Example1":{ + "description": "", + "value":{ + "error": { + "action": "set", + "error_code": 400, + "message": "Invalid or missing data in the request. Please check your input and try again.", + "pid": "8033/fkwff3000000000005k", + "pid_hash_index": "0xd454201ebc0d81a8b060d766d4e9f0556d020b4412e32b282e29d3efb43a9c9f", + "status": "rejected" + } + } + }, + "Example2":{ + "description": "", + "value":{ + "error": { + "action": "set_payload", + "error_code": 400, + "message": "Sorry, the provided payload cannot be empty. Please provide a valid payload and try again", + "pid": "8033/fkwff3000000000005k", + "pid_hash_index": "0xd454201ebc0d81a8b060d766d4e9f0556d020b4412e32b282e29d3efb43a9c9f", + "status": "rejected" + }, + "hyperdrive_op_mode": "async", + "parameter": { + "payload": {}, + "pid": "8033/fkwff3000000000005k" + } + } + } + } + } + } + }, + "500":{ + "description": "blockchain internal error response", + "content": { + "application/json":{ + "schema":{ + "oneOf": [ + { + "$ref": "#/components/schemas/generic_with_parameter_error_response" + }, + { + "$ref": "#/components/schemas/generic_without_parameter_error_response" + } + ] + } + } + } + }, + "501":{ + "description": "the server does not support the functionality required to complete the request", + "content": { + "application/json":{ + "schema":{ + "$ref": "#/components/schemas/generic_with_parameter_error_response" + } + } + } + } + } + } + }, + "/core/get/{dark_id}":{ + "summary": "retrieve a PID from blockchain", + "description": "through this route you can view all the information present in a PID stored on the blockchain", + "get":{ + "description": "", + "parameters": [ + { + "$ref": "#/components/parameters/dark_id" + } + ], + "responses": { + "200":{ + "description": "success response in json format containing the information contained in the PID submitted by the user", + "content": { + "application/json":{ + "schema":{ + "type": "object", + "description": "", + "allOf": [ + { + "$ref": "#/components/schemas/Action" + }, + { + "$ref": "#/components/schemas/Hyperdrive_op_mode" + }, + { + "$ref": "#/components/schemas/Status" + }, + { + "$ref": "#/components/schemas/Pid" + }, + { + "$ref": "#/components/schemas/Pid_hash_index" + }, + { + "type": "object", + "description": "", + "properties": { + "parameter":{ + "type": "object", + "description": "contains all the information of the submitted pid", + "allOf": [ + { + "type": "object", + "description": "", + "properties": { + "get_pid_informations":{ + "type": "object", + "description": "", + "allOf": [ + { + "type": "object", + "properties": { + "externa_pid_list":{ + "type": "array", + "description": "", + "items":{} + }, + "externa_url":{ + "type": "string", + "description": "" + } + } + }, + { + "$ref": "#/components/schemas/Payload" + }, + { + "$ref": "#/components/schemas/Pid" + } + ] + } + } + }, + { + "$ref": "#/components/schemas/Pid" + } + ] + } + + } + } + ] + }, + "example":{ + "action":"get_pid", + "hyperdrive_op_mode":"sync", + "parameter":{"get_pid_informations":{"externa_pid_list":[],"externa_url":"","payload":""},"pid":"8033/fkwff3000000000004s"}, + "pid":"8033/fkwff3000000000004s", + "pid_hash_index":"0xf6b438cb3c79162c8b06dc2bad33a3fe8ac9234710d30193f1a293d883e1e897", + "status":"executed" + } + } + } + }, + "400":{ + "description": "json format error response", + "content": { + "application/json":{ + "schema":{ + "$ref": "#/components/schemas/generic_without_parameter_error_response" + } + } + } + }, + "500":{ + "description": "blockchain internal error response", + "content": { + "application/json":{ + "schema":{ + "$ref": "#/components/schemas/generic_without_parameter_error_response" + } + } + } + } + } + } + } + }, + "components": { + "schemas": { + "generic_with_parameter_error_response":{ + "type": "object", + "description": "a schematic of a generic error response in which the user submitted an argument in the body of the request", + "allOf": [ + { + "$ref": "#/components/schemas/error_with_pid" + }, + { + "$ref": "#/components/schemas/Parameter" + }, + { + "$ref": "#/components/schemas/Hyperdrive_op_mode" + } + ] + }, + "generic_without_parameter_error_response":{ + "description": "a schematic of a generic error response where the user did not submit an argument in the request body", + "$ref": "#/components/schemas/error_with_pid" + + }, + "sync_success_response":{ + "description": "generic synchronous success response", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/Action" + }, + { + "$ref": "#/components/schemas/Status" + }, + { + "$ref": "#/components/schemas/Pid" + }, + { + "$ref": "#/components/schemas/Parameter" + }, + { + "$ref": "#/components/schemas/Hyperdrive_op_mode" + }, + { + "$ref": "#/components/schemas/Pid_hash_index" + } + ] + }, + "async_success_response":{ + "description": "generic asynchronous success response", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/Action" + }, + { + "$ref": "#/components/schemas/Status" + }, + { + "$ref": "#/components/schemas/Pid" + }, + { + "$ref": "#/components/schemas/Parameter" + }, + { + "$ref": "#/components/schemas/Hyperdrive_op_mode" + }, + { + "$ref": "#/components/schemas/Pid_hash_index" + }, + { + "$ref": "#/components/schemas/Transaction_hash" + } + ] + }, + "error_response":{ + "description": "", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/Action" + }, + { + "$ref": "#/components/schemas/Status" + }, + { + "type": "object", + "properties": { + "message":{ + "type": "string", + "description": "the error message" + }, + "error_code":{ + "type": "integer", + "description": "the error code" + } + } + } + ] + }, + "error_with_pid":{ + "type": "object", + "description": "generic error response in which the user submitted a pid or hash_pid", + "discriminator": { + "propertyName": "error" + }, + "properties": { + "error":{ + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/error_response" + }, + { + "$ref": "#/components/schemas/Pid" + }, + { + "$ref": "#/components/schemas/Pid_hash_index" + } + ] + } + } + }, + "Action": { + "type": "string", + "description": "specifies the action requested through the API. It can take on various values, including 'set_payload,' 'new_pid,' 'add_url,' and 'add_external_pid.' These values indicate different operations or tasks that the API can perform. This parameter is represented in JSON format and is available in both sync and async modes.", + "discriminator":{ + "propertyName": "action" , + "mapping": { + + } + }, + "properties": { + "action":{ + "description": "the action that is requested", + "type": "string" + } + } + }, + "Status": { + "type": "string", + "description": "reflects the status of the API request. It can have one of three values: 'executed' (indicating successful execution in sync mode), 'queued' (suggesting the task is awaiting processing in async mode), or 'rejected' (implying that the request encountered an error).", + "discriminator":{ + "propertyName": "status" + }, + "properties": { + "status":{ + "description": "the status of the request", + "type": "string" + } + } + }, + "Pid":{ + "type": "string", + "description": "This parameter represents a unique identifier for a specific object. It's returned as a string and is available in both synchronous and asynchronous modes.", + "discriminator": { + "propertyName": "pid" + }, + "properties": { + "pid":{ + "description": "the pid that the action refers.", + "type": "string" + } + } + }, + "Hyperdrive_op_mode":{ + "type": "string", + "description": "The 'hyperdrive_op_mode' parameter indicates the operational mode of HyperDrive. It can be either 'sync' or 'async', signifying synchronized or asynchronous operation, respectively.", + "discriminator": { + "propertyName": "hyperdrive_op_mode" + }, + "properties": { + "hyperdrive_op_mode":{ + "description": "the hyperdrive operation mode has two possible response", + "type": "string" + } + } + }, + "Transaction_hash":{ + "type": "string", + "description": "In asynchronous mode, the 'transaction_hash' parameter comes into play. It holds the blockchain transaction hash, represented as a hexadecimal number. If the HyperDrive is executing over the sync mode the parameter will not be presented in API response.", + "discriminator": { + "propertyName": "transaction_hash" + }, + "properties": { + "transaction_hash":{ + "description": "the blockchain transaction hash", + "type": "string" + } + } + }, + "Pid_hash_index":{ + "type": "string", + "description": "This parameter holds a blockchain internal index of the PID.", + "discriminator": { + "propertyName": "pid_hash_index" + }, + "properties": { + "pid_hash_index":{ + "description": "the pid hash values", + "type": "string" + } + } + }, + "Parameter":{ + "description": "Contains additional information required for the requested action. It's structured as JSON and may include values such as 'pid,' 'external_url,' and 'payload.' These values vary depending on the specific action requested", + "type": "object", + "discriminator": { + "propertyName": "parameter" + }, + "properties": { + "parameter":{ + "description": "the request parameters", + "type": "object" + } + } + }, + "Payload":{ + "description": "an object record that can be sent or accessed by the user through its respective PID", + "type": "object", + "discriminator": { + "propertyName": "payload" + }, + "properties": { + "payload":{ + "description": "The payload of the object record", + "type": "object" + } + } + } + }, + "securitySchemes":{ + "bearerAuth":{ + "description": "this parameter refers to the JWT access token that authorizes the user to access the Hyperdrive API methods. It is returned as a string and is available in synchronous and asynchronous modes.", + "type": "http", + "scheme": "bearer", + "bearerFormat": "JWT" + } + }, + "parameters": { + "dark_id":{ + "in": "path", + "name": "dark_id", + "description": "The dark id is a parameter submitted as an argument in the request path. It is an already existing pid or hash_pid value.", + "required": true, + "schema":{ + "type": "string" + } + } + }, + "requestBodies": { + "add_external_attributes":{ + "description": "To add external attributes to the pid, it is necessary to submit one of the following keys that will make up the body of the request: external_url or external_pid and its respective value", + "content": { + "application/json":{ + "schema":{ + "oneOf": [ + { + "properties": { + "external_url":{ + "description": "an external url", + "type": "string" + } + } + }, + { + "properties": { + "external_pid":{ + "description": "an external pid", + "type": "string" + } + } + } + ] + }, + "examples": { + "exemple1":{ + "$ref": "#/components/examples/request_body_add_external_url_exemple" + }, + "exemple2":{ + "$ref": "#/components/examples/request_body_add_external_pid_exemple" + } + } + } + }, + "required": true + }, + "set_external_attributes":{ + "description": "To set attributes external to the pid, it is necessary to submit one of the following keys that will make up the request body: external_url or payload and its respective value", + "content": { + "application/json":{ + "schema":{ + "oneOf": [ + { + "properties": { + "external_url":{ + "description": "a external url", + "type": "string" + } + } + }, + { + "$ref": "#/components/schemas/Payload" + } + ] + }, + "examples": { + "exemple1":{ + "$ref": "#/components/examples/request_body_add_external_url_exemple" + }, + "exemple2":{ + "description": "an exemple of a payload", + "value":{ + "payload":{ + "title": "Blockchain-based Privacy-PreservingRecord Linkage: enhancing data privacy in anuntrusted environment.", + "author": "Thiago Nobrega", + "type": "Article" + } + } + } + } + } + }, + "required": true + }, + "login": { + "description": "the request body is a json format composed of two keys: email and password", + "content": { + "application/json":{ + "schema":{ + "type": "object", + "required": [ + "email", "password" + ], + "properties": { + "email":{ + "description": "user email", + "type": "string" + }, + "password":{ + "description": "user password", + "type": "string" + } + } + }, + "example":{ + "email": "usuario1@example.com", + "password": "senha123" + + } + } + }, + "required": true + } + }, + "examples": { + "request_body_add_external_url_exemple":{ + "description": "an example of an external URL that the user will submit in the body of the request", + "value":{ + "external_url":"https://twitter.com/" + } + }, + "request_body_add_external_pid_exemple":{ + "description": "an example of an external PID that the user will submit in the body of the request", + "value":{ + "external_pid":"doi:/116.jdakt.7892" + } + }, + "add_external_url_async_response_exemple":{ + "description": "response when the user submits a external_url as a parameter in hyperdrive sync op mode", + "value":{ + "action": "add_url", + "hyperdrive_op_mode": "async", + "parameter": { + "external_url": "https://twitter.com/", + "pid": "8033/fkwff30000000000026" + }, + "pid": "8033/fkwff30000000000026", + "pid_hash_index": "0xc764a3c06b1f4d8f723b466541b9cfc66a88ba3ca5a02ee090e2396e065f5d1a", + "status": "queued", + "transaction_hash": "0xfe6f60bd0ac041dd0c6b3178f57acf338dae343c7985eacc7fcdd42b510868b8" + } + }, + "add_external_url_sync_response_exemple":{ + "description": "response when the user submits a external_url as a parameter in hyperdrive async op mode", + "value":{ + "action": "add_url", + "hyperdrive_op_mode": "sync", + "parameter": { + "external_url": "https://www.google.com/", + "pid": "8033/fkwff30000000000026" + }, + "pid": "8033/fkwff30000000000026", + "pid_hash_index": "0xc764a3c06b1f4d8f723b466541b9cfc66a88ba3ca5a02ee090e2396e065f5d1a", + "status": "executed" + } + }, + "error_response_exemple": { + "description": "", + "value":{ + "action": "add", + "error_code": 400, + "message": "Invalid or missing data in the request. Please check your input and try again.", + "pid": "8033/fkwff30000000000026", + "pid_hash_index": "0xc764a3c06b1f4d8f723b466541b9cfc66a88ba3ca5a02ee090e2396e065f5d1a", + "status": "rejected" + } + } + } + } +} + + +