From 94b5deee330007f6c19de0f93269f2892109e5ae Mon Sep 17 00:00:00 2001 From: Puria Nafisi Azizi Date: Thu, 17 Oct 2024 18:41:24 +0200 Subject: [PATCH] feat: Initial API draft for the gateway (#5) --- docs/public/API/index.html | 16 + docs/public/API/openapi.yml | 1197 +++++++++++++++++++++++++++++++++++ 2 files changed, 1213 insertions(+) create mode 100644 docs/public/API/index.html create mode 100644 docs/public/API/openapi.yml diff --git a/docs/public/API/index.html b/docs/public/API/index.html new file mode 100644 index 0000000..71e0835 --- /dev/null +++ b/docs/public/API/index.html @@ -0,0 +1,16 @@ + + + + + + + DIDimo 👀 Gateway API + + + + + + + + + diff --git a/docs/public/API/openapi.yml b/docs/public/API/openapi.yml new file mode 100644 index 0000000..64c6f4a --- /dev/null +++ b/docs/public/API/openapi.yml @@ -0,0 +1,1197 @@ +openapi: 3.0.1 + +info: + title: DIDimo 👀 API Gateway + description: > + DIDimo API Gateway for managing decentralized identity services, compliance checks, periodic scheduling, organizational management, and reporting. + This API provides developers, service providers, and organizations with tools to ensure compliance, manage tests, reports, and ownership claims. + version: 1.4.0 + contact: + name: DIDimo Support + email: support@forkbomb.eu + url: https://forkbomb.solutions + +servers: + - url: https://s.api.didimo.forkbomb.eu/v1 + description: Staging server + - url: https://t.api.didimo.forkbomb.eu/v1 + description: Test server + +paths: + /auth/register: + post: + summary: Register a new user + description: > + Allows a new user to register with the system by providing necessary details. + The user will receive an access token upon successful registration. + tags: + - Authentication + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/RegisterRequest' + responses: + '201': + description: User registered successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/SuccessResponse' + '400': + description: Invalid registration data. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '409': + description: User already exists. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: Internal server error during registration. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + /auth/login: + post: + summary: Log in user + description: > + Authenticates a user with their credentials and returns an access token if successful. + tags: + - Authentication + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/LoginRequest' + responses: + '200': + description: Login successful. Returns the access token. + content: + application/json: + schema: + $ref: '#/components/schemas/LoginResponse' + '401': + description: Invalid credentials. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: Internal server error during login. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + /compliance/score/{serviceId}: + get: + summary: Get the compliance score for a service + description: > + Retrieves the overall compliance score for a given service, which indicates how well the service adheres to + the standards it is measured against. + tags: + - Compliance + parameters: + - name: serviceId + in: path + required: true + schema: + type: string + description: The ID of the service for which the compliance score is being requested. + responses: + '200': + description: Successfully retrieved the compliance score. + content: + application/json: + schema: + $ref: '#/components/schemas/ComplianceScoreResponse' + '404': + description: Service not found with the provided ID. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '401': + description: Unauthorized access; valid authentication is required. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: Internal server error while retrieving the compliance score. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + /compliance/standards: + get: + summary: Get the list of available compliance standards + description: > + Fetches the list of all available compliance standards that services can be checked against. + Each standard contains information about its scope, version, and other relevant details. + tags: + - Compliance + responses: + '200': + description: Successfully retrieved the list of compliance standards. + content: + application/json: + schema: + $ref: '#/components/schemas/StandardsListResponse' + '401': + description: Unauthorized access; valid authentication is required. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: Internal server error while retrieving standards. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + /compliance/check/{serviceId}/{standardId}: + get: + summary: Check the compliance of a service against a specific standard + description: > + Evaluates the compliance of a given service against a specified standard. + This returns detailed information on which aspects of the standard the service complies with + and which areas require improvement. + tags: + - Compliance + parameters: + - name: serviceId + in: path + required: true + schema: + type: string + description: The ID of the service being evaluated. + - name: standardId + in: path + required: true + schema: + type: string + description: The ID of the compliance standard being checked. + responses: + '200': + description: Successfully checked the service compliance against the specified standard. + content: + application/json: + schema: + $ref: '#/components/schemas/ComplianceCheckResponse' + '404': + description: > + Service or standard not found with the provided ID(s). + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '401': + description: Unauthorized access; valid authentication is required. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: Internal server error during compliance check. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + /tests: + post: + summary: Upload a new compliance test + description: > + Allows developers and service providers to upload new compliance tests to the platform. + Tests can be added via API to ensure they are executed as part of the compliance checks for credentials issuers. + tags: + - Tests + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/TestSubmission' + responses: + '201': + description: Test uploaded successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/SuccessResponse' + '400': + description: Invalid test data provided. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: Internal server error while processing the test upload. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + /services: + post: + summary: Register a new service + description: > + Registers a new service under an organization. Services are associated with specific compliance checks and reports. + tags: + - Services + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceRegistration' + responses: + '201': + description: Service registered successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceResponse' + '400': + description: Invalid service data provided. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: Internal server error while registering the service. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + get: + summary: Retrieve all services + description: > + Retrieves a list of all registered services. Can be filtered by organization. + tags: + - Services + parameters: + - name: organizationId + in: query + schema: + type: string + description: Filter services by the given organization ID. + responses: + '200': + description: List of services retrieved successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/ServicesListResponse' + '500': + description: Internal server error while retrieving services. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + /services/{serviceId}: + get: + summary: Retrieve a specific service + description: > + Retrieves details about a specific service by its ID. + tags: + - Services + parameters: + - name: serviceId + in: path + required: true + schema: + type: string + description: The ID of the service to retrieve. + responses: + '200': + description: Service details retrieved successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceResponse' + '404': + description: Service not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: Internal server error while retrieving the service. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + delete: + summary: Delete a service + description: > + Deletes a service by its ID. Only authorized users with ownership rights can delete a service. + tags: + - Services + parameters: + - name: serviceId + in: path + required: true + schema: + type: string + description: The ID of the service to delete. + responses: + '200': + description: Service deleted successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/SuccessResponse' + '404': + description: Service not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: User is not authorized to delete this service. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: Internal server error while deleting the service. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + /schedule/compliance: + post: + summary: Schedule a compliance check + description: > + Schedules a compliance check for a specific service. Users can define the frequency (e.g., daily, weekly) + and set parameters for the compliance check. + tags: + - Scheduling + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ScheduleRequest' + responses: + '201': + description: Compliance check scheduled successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/SuccessResponse' + '400': + description: Invalid scheduling data or missing parameters. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '401': + description: Unauthorized access; valid authentication is required. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: Internal server error during scheduling. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + /schedule/compliance/{scheduleId}: + get: + summary: Retrieve the status of a compliance schedule + description: > + Fetches the status and details of a specific compliance schedule based on the schedule ID. + Users can see if their compliance check is pending, running, or completed. + tags: + - Scheduling + parameters: + - name: scheduleId + in: path + required: true + schema: + type: string + description: The unique ID of the compliance schedule. + responses: + '200': + description: Successfully retrieved the schedule status. + content: + application/json: + schema: + $ref: '#/components/schemas/ScheduleStatusResponse' + '404': + description: Schedule not found with the provided ID. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '401': + description: Unauthorized access; valid authentication is required. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: Internal server error while retrieving the schedule. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + /reports: + get: + summary: Retrieve public reports + description: > + Retrieves a list of public reports that can be accessed without authentication. + tags: + - Reports + responses: + '200': + description: Public reports retrieved successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/ReportsListResponse' + '500': + description: Internal server error while retrieving reports. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + post: + summary: Submit a new report + description: > + Allows users to submit a new report for a specific service. If the user is not the owner, the report can still be submitted but requires approval. + tags: + - Reports + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ReportSubmission' + responses: + '201': + description: Report submitted successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/ReportResponse' + '400': + description: Invalid report data provided. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: Internal server error while submitting the report. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + /organizations: + post: + summary: Register a new organization + description: > + Allows a user to register a new organization. The user becomes the initial owner of the organization. + tags: + - Organizations + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationRequest' + responses: + '201': + description: Organization successfully registered. + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationResponse' + '400': + description: Invalid request body. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '401': + description: Unauthorized access; valid authentication is required. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '409': + description: Organization with the same name already exists. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: Internal server error while registering the organization. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + /organizations/{organizationId}: + get: + summary: Retrieve organization details + description: > + Fetches details about a specific organization, including its services and members. + tags: + - Organizations + parameters: + - name: organizationId + in: path + required: true + schema: + type: string + description: The ID of the organization to retrieve. + responses: + '200': + description: Successfully retrieved organization details. + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationDetailsResponse' + '404': + description: Organization not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '401': + description: Unauthorized access; valid authentication is required. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: Internal server error while retrieving organization details. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + put: + summary: Update organization details + description: > + Updates the information for an organization. Only owners or administrators can update organization details. + tags: + - Organizations + parameters: + - name: organizationId + in: path + required: true + schema: + type: string + description: The ID of the organization to update. + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationUpdateRequest' + responses: + '200': + description: Successfully updated organization details. + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationResponse' + '400': + description: Invalid request body. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '401': + description: Unauthorized access; valid authentication is required. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: Access denied; user does not have sufficient permissions. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: Organization not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: Internal server error while updating the organization details. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + /organizations/{organizationId}/services: + post: + summary: Add a service under an organization + description: > + Allows adding a new service under a specific organization. Only owners or administrators of the organization can perform this action. + tags: + - Organizations + parameters: + - name: organizationId + in: path + required: true + schema: + type: string + description: The ID of the organization to which the service is being added. + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceRequest' + responses: + '201': + description: Service successfully added to the organization. + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceResponse' + '400': + description: Invalid request body. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '401': + description: Unauthorized access; valid authentication is required. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: Access denied; user does not have sufficient permissions. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: Internal server error while adding the service. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + /organizations/{organizationId}/users: + post: + summary: Add a user/owner to an organization + description: > + Adds a new user to the organization. Users can be added as members, administrators, or owners. + Only owners can add or manage other users within an organization. + tags: + - Organizations + parameters: + - name: organizationId + in: path + required: true + schema: + type: string + description: The ID of the organization to which the user is being added. + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UserRoleRequest' + responses: + '201': + description: User successfully added to the organization. + content: + application/json: + schema: + $ref: '#/components/schemas/UserResponse' + '400': + description: Invalid request body. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '401': + description: Unauthorized access; valid authentication is required. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '403': + description: Access denied; user does not have sufficient permissions. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: Internal server error while adding the user. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + /organizations/{organizationId}/claim: + post: + summary: Claim ownership of an organization + description: > + Allows a user to request ownership of an organization. This claim will be subject to approval by current owners or administrators. + tags: + - Organizations + parameters: + - name: organizationId + in: path + required: true + schema: + type: string + description: The ID of the organization for which ownership is being claimed. + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + userId: + type: string + description: The ID of the user making the claim. + responses: + '202': + description: Claim request submitted successfully and is pending approval. + content: + application/json: + schema: + $ref: '#/components/schemas/ClaimResponse' + '400': + description: Invalid request body. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '401': + description: Unauthorized access; valid authentication is required. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: Organization not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '409': + description: An existing claim is already in process. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: Internal server error while processing the claim. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + +components: + schemas: + TestSubmission: + type: object + properties: + name: + type: string + description: The name of the test. + description: + type: string + description: A brief description of the test. + content: + type: string + format: base64 + description: The encoded test script/content. + required: + - name + - content + + ServiceRegistration: + type: object + properties: + name: + type: string + description: The name of the service. + organizationId: + type: string + description: The ID of the organization this service belongs to. + description: + type: string + description: A brief description of the service. + required: + - name + - organizationId + + ServiceResponse: + type: object + properties: + serviceId: + type: string + name: + type: string + organizationId: + type: string + description: + type: string + + ServicesListResponse: + type: object + properties: + services: + type: array + items: + $ref: '#/components/schemas/ServiceResponse' + total: + type: integer + + ReportSubmission: + type: object + properties: + serviceId: + type: string + status: + type: string + enum: [COMPLIANT, NON_COMPLIANT, PENDING] + details: + type: array + items: + type: string + isPublic: + type: boolean + required: + - serviceId + - status + + ReportResponse: + type: object + properties: + reportId: + type: string + message: + type: string + + ReportsListResponse: + type: object + properties: + reports: + type: array + items: + $ref: '#/components/schemas/Report' + total: + type: integer + + SuccessResponse: + type: object + properties: + status: + type: string + example: "OK" + code: + type: integer + example: 200 + message: + type: string + example: "Operation completed successfully." + + ErrorResponse: + type: object + properties: + status: + type: string + example: "ERROR" + code: + type: integer + example: 400 + message: + type: string + example: "Bad Request" + errors: + type: array + items: + type: string + + RegisterRequest: + type: object + properties: + username: + type: string + description: The username of the user to register. + password: + type: string + format: password + description: The password for the user. + email: + type: string + format: email + description: The email address of the user. + required: + - username + - password + - email + + LoginRequest: + type: object + properties: + username: + type: string + description: The username of the user. + password: + type: string + format: password + description: The password for the user. + required: + - username + - password + + LoginResponse: + type: object + properties: + data: + type: object + properties: + accessToken: + type: string + description: The JWT access token for the authenticated user. + refreshToken: + type: string + description: The refresh token used to generate new access tokens. + ScheduleRequest: + type: object + properties: + serviceId: + type: string + description: The ID of the service for which the compliance check is scheduled. + frequency: + type: string + enum: [daily, weekly, monthly] + description: The frequency of the compliance check. + startDate: + type: string + format: date-time + description: The date and time when the first compliance check should be executed. + parameters: + type: object + additionalProperties: + type: string + description: Additional parameters for the compliance check. + required: + - serviceId + - frequency + - startDate + + ScheduleStatusResponse: + type: object + properties: + data: + type: object + properties: + scheduleId: + type: string + description: The ID of the compliance schedule. + status: + type: string + enum: [pending, running, completed, failed] + description: The current status of the compliance check. + nextRun: + type: string + format: date-time + description: The next scheduled execution time for the compliance check. + lastRun: + type: string + format: date-time + description: The last time the compliance check was executed. + resultsSummary: + type: object + properties: + successCount: + type: integer + description: The number of successful checks. + failureCount: + type: integer + description: The number of failed checks. + lastOutcome: + type: string + description: The outcome of the most recent compliance check. + required: + - scheduleId + - status + + ComplianceScoreResponse: + type: object + properties: + data: + type: object + properties: + serviceId: + type: string + description: The ID of the service for which the compliance score is being reported. + score: + type: number + format: float + description: The overall compliance score of the service (0.0 to 1.0, where 1.0 is fully compliant). + standardsComplied: + type: array + items: + type: string + description: A list of standard IDs the service complies with. + standardsPending: + type: array + items: + type: string + description: A list of standard IDs the service does not yet comply with. + required: + - serviceId + - score + + StandardsListResponse: + type: object + properties: + data: + type: array + items: + type: object + properties: + standardId: + type: string + description: The unique ID of the compliance standard. + name: + type: string + description: The name of the compliance standard. + version: + type: string + description: The version of the standard. + description: + type: string + description: A brief description of the compliance standard. + lastUpdated: + type: string + format: date-time + description: The date when the standard was last updated. + required: + - data + + ComplianceCheckResponse: + type: object + properties: + data: + type: object + properties: + serviceId: + type: string + description: The ID of the service being checked. + standardId: + type: string + description: The ID of the compliance standard being evaluated. + complianceStatus: + type: string + enum: [compliant, non-compliant, partially-compliant] + description: The compliance status of the service against the specified standard. + complianceDetails: + type: object + properties: + passedCriteria: + type: array + items: + type: string + description: A list of criteria that the service passed. + failedCriteria: + type: array + items: + type: string + description: A list of criteria that the service failed to meet. + recommendations: + type: array + items: + type: string + description: Suggested actions to achieve compliance. + required: + - serviceId + - standardId + - complianceStatus + + OrganizationRequest: + type: object + properties: + name: + type: string + description: The name of the organization. + description: + type: string + description: A brief description of the organization. + required: + - name + + OrganizationResponse: + type: object + properties: + data: + type: object + properties: + organizationId: + type: string + name: + type: string + description: + type: string + nullable: true + + OrganizationUpdateRequest: + type: object + properties: + name: + type: string + description: + type: string + + ServiceRequest: + type: object + properties: + name: + type: string + description: The name of the service being added. + details: + type: string + description: Additional information about the service. + + UserRoleRequest: + type: object + properties: + userId: + type: string + role: + type: string + enum: [member, administrator, owner] + description: The role assigned to the user within the organization. + required: + - userId + - role