specifications.yaml

openapi: 3.0.3
info:
  title: Trust service REST API
  description: This document specifies the REST API for Trust service in MODERATE
    platform.
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
externalDocs:
  description: Find out more about MODERATE
  url: https://github.com/MODERATE-Project
servers:
- url: http://127.0.0.1:8081/api
tags:
- name: Decentralized identifiers
  description: Everything about DIDs.
- name: Proofs
  description: Everything about proofs.
- name: NFTs
  description: Everything about NFTs (ERC-721).
- name: Logs
  description: Everything about log files.
paths:
  /dids:
      post:
        tags:
        - Decentralized identifiers
        summary: Create a DID and a DID document.
        description: Create a DID and a DID document.
        operationId: create_did
        responses:
          "200":
            description: Successful operation.
          "401":
            description: Access token is missing or invalid
        x-swagger-router-controller: did_service.rs
  /dids/{did}:
    get:
      tags:
      - Decentralized identifiers
      summary: Retrieve the DID document from the tangle associated to that DID.
      description: Retrieve the DID document from the tangle associated to that DID.
      operationId: get_did_doc
      parameters:
      - name: did
        in: path
        description: A DID.
        required: true
        style: simple
        explode: false
        schema:
          type: string
          example: did:iota:rms:0x6268d0021e16d6c928da7595b6b5e98712a152de9ccf9a20ed9771705b20e9a8
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DIDdocument'
      x-swagger-router-controller: did_service.rs
  /proofs:
    post:
      tags:
      - Proofs
      summary: Create and publish a proof on the Tangle.
      description: "Create and publish a proof on the Tangle. The received data\
        \ will be signed with the keypair related to that DID, the DID must be of\
        \ the owner. If not provided, it should be possible to retrieve it. A reference\
        \ to the proof output will be stored and identified with a proofId,\
        \ there should be a 1-1 relationship, between the proof and the asset."
      operationId: create_proof
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProofRequest'
        required: true
      responses:
        "200":
          description: Successful operation.
        "401":
          description: Access token is missing or invalid
      x-swagger-router-controller: proof_service.rs
    get:
      tags:
      - Proofs
      summary: Verify and return a proof given an asset id (as a query params)
      description: Returns the proof retrieved from the tangle. 
      # The method also check the integrity on the system of the
      operationId: get_proof_by_asset
      parameters:
        - in: query
          name: assetId
          description: Identifier of the asset.
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProofResponse'
      x-swagger-router-controller: proof_service.rs
  /proofs/{proofId}:
    get:
      tags:
      - Proofs
      summary: Verify and return a proof
      description: Returns the proof retrieved from the tangle. 
      # The method also check the integrity on the system of the
      operationId: get_proof
      parameters:
      - name: proofId
        in: path
        description: Identifier of the proof.
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProofResponse'
      x-swagger-router-controller: proof_service.rs
  /nfts:
    post:
      tags:
      - NFTs
      summary: Mint an NFT
      description: "Specifically, the service will mint the NFT by interacting with the AssetFactory smart contract. The NFT address is stored within the database, there should be a 1-1 relationship, between the NFT and the asset."
      operationId: mint_nft
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NftRequest'
        required: true
      responses:
        200:
          description: Nft minted. Successful operation.
    get:
      tags:
      - NFTs
      summary: Return the NFT information given an asset id (as a query params)
      description: Returns the license and read from the NFT smart contract. 
      operationId: read_nft
      parameters:
        - in: query
          name: assetId
          description: Identifier of the asset.
          required: true
          schema:
            type: string
      responses:
        200:
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NftResponse'
  /log:
    get:
      tags:
        - Logs
      summary: Retrieve the log file
      description: "This endpoint retrieves the log file from IPFS using the CID (Content Identifier) stored in the conventional storage. The file corresponding to the CID will be sent back to the client."
      operationId: get_log
      responses:
        200:
          description: File retrieved successfully
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary

components:
  schemas:
    ProofRequest:
      required:
      - assetId
      - assetHash
      - metadataHash
      - did
      properties:
        assetId: 
          type: string
          description: Identifier of the asset
        assetHash:
          type: string
          description: Hash of the asset for which the service will create a proof.
        metadataHash:
          type: string
          description: Hash of the metadata of the asset
        did:
          type: string
          description: DID of the user, owner of the asset
      description: Input for building the Proof
    ProofResponse:
      description: Proof in JWS format
    DIDdocument:
      description: A DID document as defined in the [DID standard](https://www.w3.org/TR/did-core/)
    NftRequest:
      required:
      - assetId
      - nftAlias
      - nftSymbol
      - license
      - did
      properties:
        assetId:
          type: string
          description: Identifier of the asset
        nftSymbol:
          type: string
          description: Symbol of the NFT
        nftAlias:
          type: string
          description: Name for the NFT
        license:
          type: string
          description: License in SPDX format chosen by the asset owner and stored within the NFT
        did:
          type: string
          description: DID of the user, owner of the asset
      description: Input for minting the NFT
    NftResponse:
      properties:
        assetId:
          type: string
          description: Identifier of the asset
        nftAddress:
          type: string
          description: Address of the NFT
        license:
          type: string
          description: License in SPDX format chosen
        did:
          type: string
          description: DID of the user, owner of the asset
      description: Input for minting the NFT
    LogFileResponse:
      type: string
      format: binary
      description: The log file content

  responses:
    UnathorizedError:
      description: Access token is missing or invalid