@windingtree/wt-write-api/docs/source.yaml

API to write data to the Winding Tree platform

openapi: 3.0.0
servers:
  - description: Demo deployment
    url: 'https://demo-write-api.windingtree.com'
  - description: Localhost
    url: 'http://localhost:8000'
info:
  description: API for creating and updating inventory in Winding Tree platform
  version: 'will-be-set-at-runtime'
  title: WT Write API
paths:
  /:
    get:
      summary: API info
      responses:
        '200':
          description: Basic information about this API instance.
          content:
            application/json:
              schema:
                type: object
                required:
                  - docs
                  - info
                  - version
                  - config
                  - wtDirectoryAddress
                  - wtFactoryAddress
                  - ethNetwork
                  - dataFormatVersions
                properties:
                  docs:
                    type: string
                    description: Link to the API documentation.
                  info:
                    type: string
                    description: Link to more information about the API.
                  version:
                    type: string
                    description: Deployed API version number.
                  config:
                    type: string
                    description: Which config is the API using. It might be useful to name configs after used ETH networks.
                  wtDirectoryAddress:
                    type: string
                    description: Ethereum address of used Winding Tree Directory.
                  wtFactoryAddress:
                    type: string
                    description: Ethereum address of used Winding Tree Factory.
                  ethNetwork:
                    type: string
                    description: Name of the ethereum network against which this instance runs.
                  dataFormatVersions:
                    description: Version number indicating the data format specification version.
                    type: object
                    properties:
                      hotels:
                        type: string
  /accounts:
    post:
      summary: Create account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Account'
      responses:
        '200':
          description: ID and access key for the created account.
          content:
            application/json:
              schema:
                type: object
                properties:
                  accountId:
                    type: string
                    description: ID of the created account.
                  accessKey:
                    type: string
                    description: Access key to be used for authentication when communicating with the API.
        '400':
          $ref: '#/components/responses/BadRequestError'
        '422':
          $ref: '#/components/responses/UnprocessableEntityError'
  '/accounts/{accountId}':
    parameters:
      - name: accountId
        required: true
        in: path
        description: Account ID as returned by POST /accounts
        schema:
          type: string
    put:
      summary: Update account
      security:
        - AccessKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Account'
      responses:
        '204':
          description: Account was successfully updated.
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '422':
          $ref: '#/components/responses/UnprocessableEntityError'
    delete:
      summary: Delete account
      security:
        - AccessKey: []
      responses:
        '204':
          description: Account was successfully deleted.
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '422':
          $ref: '#/components/responses/UnprocessableEntityError'
  /hotels:
    post:
      summary: Create hotel in WT.
      security:
        - AccessKey: []
          WalletPassword: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Organization'
      responses:
        '201':
          description: Ethereum address of the created hotel.
          content:
            application/json:
              schema:
                type: object
                properties:
                  address:
                    type: string
                    description: Address of the created hotel
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '422':
          $ref: '#/components/responses/UnprocessableEntityError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
  '/hotels/{hotelAddress}':
    parameters:
      - name: hotelAddress
        required: true
        in: path
        description: Hotel address as returned by POST /hotels
        schema:
          type: string
    get:
      summary: Get hotel (provided for convenience to make updates easier) from WT.
      responses:
        '200':
          description: Ethereum address of the created hotel.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/UnprocessableEntityError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
    delete:
      summary: Remove hotel from WT.
      security:
        - AccessKey: []
          WalletPassword: []
      parameters:
        - name: offChain
          required: false
          in: query
          description: If true, off-chain data will be deleted as well (if possible). Default is false.
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
      responses:
        '204':
          description: Hotel was successfully deleted.
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/UnprocessableEntityError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
    put:
      summary: >-
        Update hotel even if original off-chain data is inaccessible.
        Replaces all of the data. Can't use partial update.
      security:
        - AccessKey: []
          WalletPassword: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Organization'
      responses:
        '204':
          description: Hotel was successfully updated.
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/UnprocessableEntityError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
    patch:
      summary: >-
        Update hotel only when original off-chain data can be accessed.
        It is possible to send one of `hotel` or `legalEntity` for partial update.
      security:
        - AccessKey: []
          WalletPassword: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationPatch'
      responses:
        '204':
          description: Hotel was successfully updated.
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/UnprocessableEntityError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
  '/hotels/{hotelAddress}/transfer':
    parameters:
      - name: hotelAddress
        required: true
        in: path
        description: Hotel address as returned by POST /hotels
        schema:
          type: string
    post:
      summary: Transfer hotel to a different manager.
      security:
        - AccessKey: []
          WalletPassword: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - to
              properties:
                to:
                  type: string
                  description: Ethereum address of the new manager.
      responses:
        '204':
          description: Hotel was successfully transferred.
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/UnprocessableEntityError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
components:
  securitySchemes:
    AccessKey:
      type: apiKey
      in: header
      name: X-Access-Key
    WalletPassword:
      type: apiKey
      in: header
      name: X-Wallet-Password
  responses:
    BadRequestError:
      description: The server does not understand the request (HTTP code 400)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFoundError:
      description: The object was not found (HTTP code 404)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnauthorizedError:
      description: >-
        Authentication is requested for manipulation of the given resource.
        (Authentication can be achieved by means of two request headers - `X-Access-Key` and `X-Wallet-Password`.)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ForbiddenError:
      description: The existing authorization does not give the user permissions for the requested operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ConflictError:
      description: Data cannot be uploaded, typically because of missing uploader configuration.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntityError:
      description: Request body or params validation failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadGatewayError:
      description: The request could not be completed due to upstream errors.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Wallet:
      type: object
      description: Web3 secret storage - see https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition.
      required:
        - address
        - crypto
        - id
        - version
      properties:
        address:
          type: string
        crypto:
          type: object
          required:
            - cipher
            - ciphertext
            - cipherparams
            - kdf
            - kdfparams
            - mac
          properties:
            cipher:
              type: string
            ciphertext:
              type: string
            cipherparams:
              type: object
            kdf:
              type: string
            kdfparams:
              type: object
            mac:
              type: string
        id:
          type: string
        version:
          type: integer
    Swarm:
      description: Ethereum Swarm uploader configuration
      type: object
      required:
        - swarm
      properties:
        swarm:
          type: object
          properties: {}
    S3:
      description: AWS S3 uploader configuration
      type: object
      required:
        - s3
      properties:
        s3:
          type: object
          required:
            - accessKeyId
            - secretAccessKey
            - region
            - bucket
          properties:
            accessKeyId:
              type: string
            secretAccessKey:
              type: string
            region:
              type: string
            bucket:
              type: string
            keyPrefix:
              type: string
    Uploader:
      description: Uploader configuration for a single document type.
      oneOf:
        - $ref: '#/components/schemas/S3'
        - $ref: '#/components/schemas/Swarm'
    UploaderConfig:
      type: object
      description: Off-chain uploader configuration for the account.
      properties:
        root:
          $ref: '#/components/schemas/Uploader'
        description:
          $ref: '#/components/schemas/Uploader'
        ratePlans:
          $ref: '#/components/schemas/Uploader'
        availability:
          $ref: '#/components/schemas/Uploader'
    Account:
      type: object
      required:
        - wallet
        - uploaders
      properties:
        wallet:
          $ref: '#/components/schemas/Wallet'
        uploaders:
          $ref: '#/components/schemas/UploaderConfig'
    Organization:
      oneOf:
        - $ref: '#/components/schemas/OrganizationWithoutData'
        - allOf:
          - $ref: '#/components/schemas/OrganizationWithData'
          - type: object
            description: Organization data.
            required:
              - description
    OrganizationPatch:
      oneOf:
        - $ref: '#/components/schemas/OrganizationWithoutData'
        - allOf:
          - $ref: '#/components/schemas/OrganizationWithData'
          - type: object
            description: Patch object to update existing organization data.
    OrganizationWithData:
      type: object
      required:
        - legalEntity
        - hotel
      properties:
        legalEntity:
          $ref: '@windingtree/wt-organization-schemas/swagger.yaml#/components/schemas/LegalEntity'
        guarantee:
          $ref: '@windingtree/wt-organization-schemas/swagger.yaml#/components/schemas/Guarantee'
        hotel:
          type: object
          description: Hotel data.
          required:
            - description
          properties:
            defaultLocale:
              $ref: '@windingtree/wt-shared-schemas/swagger.yaml#/components/schemas/LanguageCodeType'
              description: Code of language in which all textual information for this record is presented. If no default locale is declared, the texts are expected to be in English language.
            description:
              $ref: '@windingtree/wt-hotel-schemas/swagger.yaml#/components/schemas/HotelDescription'
            ratePlans:
              $ref: '@windingtree/wt-hotel-schemas/swagger.yaml#/components/schemas/RatePlans'
            availability:
              $ref: '@windingtree/wt-hotel-schemas/swagger.yaml#/components/schemas/Availability'
            notifications:
              description: URL of a notification service.
              $ref: '@windingtree/wt-shared-schemas/swagger.yaml#/components/schemas/UriType'
            booking:
              description: URL of a booking service.
    OrganizationWithoutData:
      type: object
      required:
        - orgJson
        - hash
      properties:
        orgJson:
          description: URL of the ORG.JSON.
          $ref: '@windingtree/wt-shared-schemas/swagger.yaml#/components/schemas/UriType'
        hash:
          description: kecak256 hash of the ORG.JSON contents with 0x prefix
          type: 'string'
    Error:
      title: Error
      description: Default schema for errors returned by API.
      properties:
        status:
          type: number
          description: HTTP status
        code:
          type: string
          description: Computer-readable error. Use this for comparison.
        short:
          type: string
          description: Human-readable error with a short description of the error.
        long:
          type: string
          description: Verbose explanation of what happened.