open-api.yaml

# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements.  See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership.  The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License.  You may obtain a copy of the License at
#
#   http:#www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.

openapi: 3.0.0
info:
  title: Apache Milagro Server
  description: Milagro Secure - distributed / decentralized core security services. This is the HTTP API specification for the D-TA when it is running no plugins.
  contact:
    email: dev@milagro.apache.org
  license:
    name: http://www.apache.org/licenses/LICENSE-2.0
  version: 1.0.0  
paths:
  /v1/identity:
    post:
      summary: Create an Identity Document
      tags:
        - identity      
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                Name:
                  type: string
                  example: ExampleNodeName             
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateIdentityResponse'
        '400':
          description: Invalid Request
          content:
            text/plain:
             schema:
              type: string
    get:
      summary: Get a list of identity documents
      tags:
       - identity
      parameters: 
        - name: page
          in: query
          description: current page
          schema:
            type: integer
            default: 0
        - name: perPage
          in: query
          description: number of items to show
          schema:
            type: integer
            default: 10
        - name: sortBy
          in: query
          description: Sort By field. Prefix with "-" for descending
          schema:
            type: string
            enum:
              - dateCreatedAsc               
              - dateCreatedDesc               
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityListResponse'
        '400':
          description: Invalid Request
          content:
            text/plain:
              schema:
                type: string
  /v1/identity/{IDDocumentCID}:
    get:
      summary: Get Details of an Identity
      tags:
        - identity
      parameters: 
        - name: IDDocumentCID
          in: path
          description: IPFS hash address of Identity Document
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Identity'
        '400':
          description: Invalid Request
          content:
            text/plain:
              schema:
                type: string
  /v1/order:
    post:
      summary: Create an order for a new Commitment
      description: This request will return a Commitment (SECP256 public key) from the Master Fiduciary. The response also includes IPFS hash adresses of the Order Documents passed between the Principal and Master Fiduciary.
      tags:
      - order
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                BeneficiaryIDDocumentCID:
                  type: string                  
                  example: QmZJGAuHEzf3arcEDdRzS4ZVRY1onmQG3NCn9mXEYD4eon
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '400':
          description: Invalid Request
          content:
            text/plain:
              schema:
                type: string
    get:
      summary: Get a list of orders managed by this D-TA
      tags: 
      - order
      parameters: 
        - name: page
          in: query
          description: current page
          schema:
            type: integer
            default: 0
        - name: perPage
          in: query
          description: number of items to show
          schema:
            type: integer
            default: 10
        - name: sortBy
          in: query
          description: Sort By field. Prefix with "-" for descending
          schema:
            type: string
            enum:
              - dateCreatedAsc               
              - dateCreatedDesc
      responses:
        '200':
          description: Succesful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderListResponse'
        '400':
          description: Invalid Request
          content:
            text/plain:
             schema:
              type: string
  /v1/order/{OrderReference}:
    get:
      summary: Get details of an order
      tags:
      - order
      parameters:
      - name: OrderReference
        in: path
        description: Reference for a single order
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Succesful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetOrderResponse'
        '400':
          description: Invalid Request
          content:
            text/plain:
             schema:
              type: string
  /v1/order/secret:
    post:
      summary: Returns the SECP256 Secret Key
      tags:
        - order
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                OrderReference:
                  type: string                  
                  example: 9f3ac746-c418-11e9-b78c-acde48001122
                BeneficiaryIDDocumentCID:
                  type: string                  
                  example: QmfWg5GffUEzwahd9hkvdnqTGQs5PfusoEpx3kSDSdG4ze
      responses:
        '200':
          description: Succesful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderSecretResponse'
        '400':
          description: Invalid Request
          content:
            text/plain:
             schema:
              type: string
  /v1/fulfill/order:
    post:
      summary: Create Public Address
      tags:
        - fulfill      
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                OrderPart1CID:
                  type: string
                  example: Qme5S5xVfGYF46oftiLQDevPAGSKy1aggdtrZvvEdiXuqM
                DocumentCID:
                  type: string
                  example: Qme5S5xVfGYF46oftiLQDevPAGSKy1aggdtrZvvEdiXuqM
      responses:
        '200':           
          description: Succesful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FulfillOrderResponse'
        '400':
          description: Invalid Request
          content:
            text/plain:
             schema:
              type: string
  /v1/fulfill/order/secret:
    post:
      summary: Return Private Key
      tags:
        - fulfill      
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                OrderPart3CID:
                  type: string
                SenderDocumentCID:
                  type: string                                  
      responses:
        '200':
          description: Succesful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FulfillOrderSecretResponse'
        '400':
          description: Invalid Request
          content:
            text/plain:
             schema:
              type: string
  /v1/status:
    get:
      description: Test Server Health
      tags:
        - system      
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '400':
          description: Invalid Request
          content:
            text/plain:
              schema:
                type: string
servers:
  - url: 'http://localhost:5556'
  - url: 'http://localhost:5558' 
components:
  schemas:
      CreateIdentityResponse:
        type: object
        properties:
          IDDocumentCID:
            type: string      
      IdentityListResponse:
        type: object
        properties:
          IDDocumentList:
            type: array
            items: 
              $ref: '#/components/schemas/Identity'    
      Identity:
        type: object
        properties:
          IDDocumentCID:
            type: string
          AuthenticationReference:  
            type: string
          BeneficiaryECPublicKey: 
            type: string          
          SikePublicKey:            
            type: string
          BlsPublicKey:
            type: string                
          Timestamp:
            type: integer
      OrderResponse:
        type: object
        properties:
          OrderReference:
            type: string
          Commitment:
            type: string
          CreatedAt:
            type: string
      OrderListResponse:
        type: object
        properties:
          OrderReference:
            type: array
            items:
              type: string
      GetOrderResponse:
        type: object
        properties:
          Order:
            type: object
            properties:
              Order: 
                type: string
              TimeStamp:
                type: integer                            
      OrderSecretResponse:
        type: object
        properties:
          Secret:
            type: string
          Commitment:
            type: string
          OrderReference:
            type: string
      FulfillOrderResponse:
        type: object
        properties: 
          OrderPart2CID:
            type: string
      FulfillOrderSecretResponse:
        type: object
        properties:
          OrderPart4CID:
            type: string
      StatusResponse:
        type: object
        properties:
          application:
            type: string
          apiVersion:
              type: string
          extensionVendor:
            type: string
          nodeCID:
            type: string
          timeStamp:
            type: string
          plugin:
            type: string
          nodeType:
            type: string
tags:
  - name: identity
    description: Actors in the system
    externalDocs:
      url: 'https://milagro.apache.org/docs/milagro-intro/'
      description: Apache Milagro Docs
  - name: order
    description: Communication between Principals and Master Fiduciaries
    externalDocs:
      url: 'https://milagro.apache.org/docs/milagro-intro/'
      description: Apache Milagro Docs
  - name: fulfill
    description: Actions performed by the Master Fiduciary
    externalDocs:
      url: 'https://milagro.apache.org/docs/milagro-intro/'
      description: Apache Milagro Docs
  - name: system
    description: Test Server Health
    externalDocs:
      url: 'https://milagro.apache.org/docs/milagro-intro/'
      description: Apache Milagro Docs