openapi: '3.0.3'
info:
  title: Defungify API
  version: '1.0'
  description: |
    # Defungify NFT Query API
    If you know a user's wallet ID you can query the wallet for NFT's that were minted by you.
    
    You can query by wallet, user and by NFT token id's
    
    You can also validate that the user own's the wallet.
    
    API responds to either `/v1/endpoint` or `/demo1/endpoint`.  The demo1 endpoints return fake data to validate your code.
    
    Currently only OpenSea is supported.
servers:
  - url: https://localhost:5000/v1
  - url: https://localhost:5000/demo1
components: 
  securitySchemes:
    auth:
      # Authentication with an API key sent as a query string
      type: apiKey
      description: API key provided to the developer by the customer representative 
      in: header
      name: X-API-KEY
paths:
  /v1/validateWalletStep1:
    post:
      description: |
          The purpose of this api call is to start a 2 step process to validate whether a user owns the wallet that they claim is theirs.
  
          When using the `/demo1` endpoint, any userId is valid, except `bad`.  If you pass `bad`, you will get a 400 error.
          
          The return is `secureCode`, it is a random UUID.  You need to ask the user to create an NFT on their OpenSea account, using this code as part of the text of that NFT.
          
          This will **not** cost the user any `gas` (meaning money).  When you call the `validateWalletStep2`, we can validate if they truly own it.
      security:
        - auth: []
      parameters:
        - name: userId
          in: query
          description: The ID of the user, on OpenSea
          required: true
          schema:
            type: string
            example: 1234-456-789
        - name: failType
          in: query
          description: |
            This is optional and **only** valid for the `/demo1/` endpoint.
          schema:
            type: integer
            enum:
              - 400
              - 500
            example: 400
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                type: object
                properties:
                  secureCode:
                    type: string
                    description: A UUID string, that is required for step 2.
                    example: "ed0fe1c2-d529-468a-a4c9-5a504d11208d"
  /v1/validateWalletStep2:
    post:
      description: |
        In `validateWalletStep1`, you were passed a UUID that you need to ask the user to create an NFT on OpenSea using their wallet.
        
        Now when they create that NFT, OpenSea takes them to a `url`, that `url` is what you pass to this call.
        
        To test your code on this using the `/demo1/` end point, to get a failure you can pass failType of 400 or 500 to get a failure response of that type.
      security:
        - auth: []
      parameters:
        - name: url
          in: query
          description: URL of the generated NFT on OpenSea
          required: true
          schema:
            type: string
        - name: failType
          in: query
          description: |
            This is optional and **only** valid for the `/demo1/` endpoint.
          schema:
            type: integer
            enum:
              - 400
              - 500
            example: 400
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                type: object
                properties:
                  result:
                    type: string
                    description: Success
                    example: "success. Note: data not validated"
  /v1/byUserId:
    post:
      description: |
        This will return all NFT's owned by this userId.

        This call uses cached data, call `byUserIDUNCACHED` to go to OpenSea directly.

        To test your code on this using the `/demo1/` end point, to get a failure you can pass failType of 400 or 500 to get a failure response of that type.
      security:
        - auth: []
      parameters:
        - name: userId
          in: query
          required: true
          description: The ID of the user
          schema:
            type: string
        - name: failType
          in: query
          description: |
            This is optional and **only** valid for the `/demo1/` endpoint.
          schema:
            type: integer
            enum:
              - 400
              - 500
            example: 400
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                type: array
                items: 
                  type: object
                  properties:
                    tokenName:
                      type: string
                      example: WITH META DATA
                    collectionName:
                      type: string
                      example: Collection#1
                    tokenId:
                      type: string
                      example: 1001
                    imageUrl:
                      type: string
                      example: http://example.com/nft1.png
                      format: uri
                    permalink:
                      type: string
                      example: http://example.com/nft1
                      format: uri
                    owner:
                      type: string
                    description:
                      type: string
                      example: This is an example of an item with metadata
                    metadata:
                      type: array
                      items:
                        type: object
                        properties:
                          trait_type:
                            type: string
                            example: damage
                          value: 
                            type: string
                            example: 1d8
                          display_type:
                            type: string
                            example: null
                          max_value:
                            type: string
                            example: null
                          trait_count:
                            type: string
                            example: 1
                          order:
                            type: string
                            example: null
  /v1/byWallet:
    post:
      description: |
        This will return all NFT's contained in this wallet.

        This call uses cached data, call `byWalletIDUNCACHED` to go to OpenSea directly.

        To test your code on this using the `/demo1/` end point, to get a failure you can pass failType of 400 or 500 to get a failure response of that type.
      security:
        - auth: []
      parameters:
        - name: walletAddress
          in: query
          required: true
          description: The ID of the user's wallet
          schema:
            type: string
        - name: failType
          in: query
          description: |
            This is optional and **only** valid for the `/demo1/` endpoint.
          schema:
            type: integer
            enum:
              - 400
              - 500
            example: 400
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                type: array
                items: 
                  type: object
                  properties:
                    tokenName:
                      type: string
                      example: WITH META DATA
                    collectionName:
                      type: string
                      example: Collection#1
                    tokenId:
                      type: string
                      example: 1001
                    imageUrl:
                      type: string
                      example: http://example.com/nft1.png
                      format: uri
                    permalink:
                      type: string
                      example: http://example.com/nft1
                      format: uri
                    owner:
                      type: string
                    description:
                      type: string
                      example: This is an example of an item with metadata
                    metadata:
                      type: array
                      items:
                        type: object
                        properties:
                          trait_type:
                            type: string
                            example: damage
                          value: 
                            type: string
                            example: 1d8
                          display_type:
                            type: string
                            example: null
                          max_value:
                            type: string
                            example: null
                          trait_count:
                            type: string
                            example: 1
                          order:
                            type: string
                            example: null
  /byWalletUNCACHED:
    post:
      description: |
        This will return all NFT's contained in this wallet.

        This call bypasses the cache and directly queries OpenSea, this call takes more time.

        To test your code on this using the `/demo1/` end point, to get a failure you can pass failType of 400 or 500 to get a failure response of that type.
      security:
        - auth: []
      parameters:
        - name: walletAddress
          in: query
          required: true
          description: The ID of the user's wallet
          schema:
            type: string
        - name: failType
          in: query
          description: |
            This is optional and **only** valid for the `/demo1/` endpoint.
          schema:
            type: integer
            enum:
              - 400
              - 500
            example: 400
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                type: array
                items: 
                  type: object
                  properties:
                    tokenName:
                      type: string
                      example: WITH META DATA
                    collectionName:
                      type: string
                      example: Collection#1
                    tokenId:
                      type: string
                      example: 1001
                    imageUrl:
                      type: string
                      example: http://example.com/nft1.png
                      format: uri
                    permalink:
                      type: string
                      example: http://example.com/nft1
                      format: uri
                    owner:
                      type: string
                    description:
                      type: string
                      example: This is an example of an item with metadata
                    metadata:
                      type: array
                      items:
                        type: object
                        properties:
                          trait_type:
                            type: string
                            example: damage
                          value: 
                            type: string
                            example: 1d8
                          display_type:
                            type: string
                            example: null
                          max_value:
                            type: string
                            example: null
                          trait_count:
                            type: string
                            example: 1
                          order:
                            type: string
                            example: null
  /byTokenAddress:
    post:
      description: |
        Get data about the NFT.  Will use the cache if available.

        To test your code on this using the `/demo1/` end point, to get a failure you can pass failType of 400 or 500 to get a failure response of that type.
      security:
        - auth: []
      parameters:
        - name: walletAddress
          in: query
          required: true
          description: The ID of the user's wallet
          schema:
            type: string
        - name: failType
          in: query
          description: |
            This is optional and **only** valid for the `/demo1/` endpoint.
          schema:
            type: integer
            enum:
              - 400
              - 500
            example: 400
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                type: array
                items: 
                  type: object
                  properties:
                    tokenName:
                      type: string
                      example: WITH META DATA
                    collectionName:
                      type: string
                      example: Collection#1
                    tokenId:
                      type: string
                      example: 1001
                    imageUrl:
                      type: string
                      example: http://example.com/nft1.png
                      format: uri
                    permalink:
                      type: string
                      example: http://example.com/nft1
                      format: uri
                    owner:
                      type: string
                    description:
                      type: string
                      example: This is an example of an item with metadata
                    metadata:
                      type: array
                      items:
                        type: object
                        properties:
                          trait_type:
                            type: string
                            example: damage
                          value: 
                            type: string
                            example: 1d8
                          display_type:
                            type: string
                            example: null
                          max_value:
                            type: string
                            example: null
                          trait_count:
                            type: string
                            example: 1
                          order:
                            type: string
                            example: null
  /byTokenAddressUNCACHED:
    post:
      description: |
        Get data about the NFT.  Will query OpenSea directly and will take more time.

        To test your code on this using the `/demo1/` end point, to get a failure you can pass failType of 400 or 500 to get a failure response of that type.
      security:
        - auth: []
      parameters:
        - name: walletAddress
          in: query
          required: true
          description: The ID of the user's wallet
          schema:
            type: string
        - name: failType
          in: query
          description: |
            This is optional and **only** valid for the `/demo1/` endpoint.
          schema:
            type: integer
            enum:
              - 400
              - 500
            example: 400
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                type: array
                items: 
                  type: object
                  properties:
                    tokenName:
                      type: string
                      example: WITH META DATA
                    collectionName:
                      type: string
                      example: Collection#1
                    tokenId:
                      type: string
                      example: 1001
                    imageUrl:
                      type: string
                      example: http://example.com/nft1.png
                      format: uri
                    permalink:
                      type: string
                      example: http://example.com/nft1
                      format: uri
                    owner:
                      type: string
                    description:
                      type: string
                      example: This is an example of an item with metadata
                    metadata:
                      type: array
                      items:
                        type: object
                        properties:
                          trait_type:
                            type: string
                            example: damage
                          value: 
                            type: string
                            example: 1d8
                          display_type:
                            type: string
                            example: null
                          max_value:
                            type: string
                            example: null
                          trait_count:
                            type: string
                            example: 1
                          order:
                            type: string
                            example: null