openapi.yaml

openapi: 3.0.1
info:
  version: "0.1.0"
  title: Po.et Frost API
  description: Po.et Frost API OpenAPI definition
servers:
  - description: QA
    url: https://frost-api.qa.poetnetwork.net
  - description: Production
    url: https://api.frost.po.et
paths:
  /health:
    get:
      operationId: healthCheck
      summary: An API health check that returns an OK if all is well.
      responses: 
        '200':
          description: OK
  /accounts:
    post:
      operationId: createAccount
      summary: Create a new account in Frost.
      description: <b>Email</b> required (must be a valid email address format)<br> <b>Password</b> required (minimum 10 characters, maximum 30 characters, 1 lowercase, 1 uppercase, 1 numeric, 1 symbol)
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Account'
            example:
              email: 'frost@po.et'
              password: 'Letters123456!'
      responses:
        '200':
          description: "{ \"token\": \"12345abcde6789FGHI\" }"
        '409':
          description: The specified account already exists.
        '422':
          description: One of the inputs is not valid.
        '500':
          description: The server encountered an internal error. Please retry the request.
  /accounts/profile:
    get:
      operationId: getProfile
      summary: Returns the user profile.
      parameters:
        - in: header
          name: token
          schema: 
            type: string
          required: true
      responses: 
        '200':
          description: OK
          content:
            application/json:
              schema: 
                $ref: '#/components/schemas/Profile'
        '403':
          description: Server failed to authenticate the request. Make sure the value of the Authorization header is formed correctly including the signature.
        '409':
          description: The specified account is not verified.
        '500':
          description: The server encountered an internal error. Please retry the request.
  /accounts/verify:
    post:
      operationId: resendVerifyEmail
      summary: Resend the verification email.
      parameters:
        - in: header
          name: token
          schema:
            type: string
          required: true
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request.
        '403':
          description: Server failed to authenticate the request. Make sure the value of the Authorization header is formed correctly including the signature.
        '500':
          description: The server encountered an internal error. Please retry the request.
  /accounts/verify/{token}:
    get:
      operationId: verifyAccount
      summary: Verify email address by confirming receipt of a token.
      parameters:
        - name: token
          in: path
          required: true
          schema:
            type: string
            minimum: 1
      responses:
        '200':
          description: OK
        '500':
          description: The server encountered an internal error. Please retry the request.
  /login:
    post:
      operationId: loginAccount
      summary: Login to receive an access token for the API.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Account'
            example:
              email: 'frost@po.et'
              password: 'Letters123456!'
      responses:
        '200':
          description: "{ \"token\": \"12345abcde6789FGHI\" }"
        '400':
          description: The specified resource does not exist.
        '422':
          description: One of the inputs is not valid.
        '500':
          description: The server encountered an internal error. Please retry the request.
  /password/reset:
    post:
      operationId: passwordReset
      summary: Reset account password if lost/forgotten.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - 'email'
              properties:
                email:
                  type: string
            example:
              email: 'frost@po.et'
      responses:
        '200':
          description: OK
        '400':
          description: The specified resource does not exist.
        '500':
          description: The server encountered an internal error. Please retry the request.
  /password/change:
    post:
      operationId: passwordChange
      summary: Change account password.
      parameters:
        - in: header
          name: token
          schema:
            type: string
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - 'password'
                - 'oldPassword'
              properties:
                password:
                  type: string
                oldPassword:
                  type: string
            example:
              password: 'NeWpA$sw0rd'
              oldPassword: 'OlDpa$sw0rd'
      responses:
        '200':
          description: OK
        '403':
          description: Server failed to authenticate the request. Make sure the value of the Authorization header is formed correctly including the signature.
        '409':
          description: The specified account is not verified.
        '422':
          description: One of the inputs is not valid.
        '500':
          description: The server encountered an internal error. Please retry the request.
  /password/change/token:
    post:
      operationId: passwordChangeToken
      summary: Change account password with token sent by email.
      parameters:
        - in: header
          name: token
          schema:
            type: string
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - 'password'
              properties:
                password:
                  type: string
            example:
              password: 'NeWpA$sw0rd'
      responses:
        '200':
          description: OK
        '403':
          description: Server failed to authenticate the request. Make sure the value of the Authorization header is formed correctly including the signature.
        '409':
          description: The specified account is not verified.
        '422':
          description: One of the inputs is not valid.
        '500':
          description: The server encountered an internal error. Please retry the request.
  /tokens:
    post:
      operationId: createToken
      summary: Create a new API token.
      parameters:
        - in: header
          name: token
          schema:
            type: string
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenNew'
            example:
              network: 'live'
      responses:
        '200':
          description: OK
        '400':
          description: Could not create the work.
        '403':
          description: Server failed to authenticate the request. Make sure the value of the Authorization header is formed correctly including the signature.
        '409':
          description: The specified account is not verified.
        '413':
          description: Request entity is too large.
        '422':
          description: One of the inputs is not valid.
        '500':
          description: The server encountered an internal error. Please retry the request.
    get:
      operationId: getTokens
      summary: Returns an array of API tokens.
      parameters:
        - in: header
          name: token
          schema: 
            type: string
          required: true
      responses: 
        '200':
          description: "{ \"apiTokens\": [ \"12345abcde6789FGHI\", \"TEST_6789fegh35sk\" ] }"
        '403':
          description: Server failed to authenticate the request. Make sure the value of the Authorization header is formed correctly including the signature.
        '500':
          description: The server encountered an internal error. Please retry the request.
  /tokens/{tokenId}:
    delete:
      operationId: deleteToken
      summary: Delete an API token by Id.
      parameters:
        - in: path
          name: tokenId
          schema:
            type : string
            minimum: 1
          required: true
        - in: header
          name: token
          schema:
            type: string
          required: true
      responses: 
        '200':
          description: OK
          content:
            application/json:
              schema: 
                $ref: '#/components/schemas/Tokens'
        '400':
          description: The specified resource does not exist.
        '403':
          description: Server failed to authenticate the request. Make sure the value of the Authorization header is formed correctly including the signature.
        '422':
          description: Invalid token.
        '500':
          description: The server encountered an internal error. Please retry the request.
  
  /works:
    post:
      operationId: createWork
      summary: Add a new work to the Po.et Network.
      parameters:
        - in: header
          name: token
          schema:
            type: string
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Work'
      responses:
        '200':
          description: OK
        '400':
          description: Could not create the work.
        '403':
          description: Server failed to authenticate the request. Make sure the value of the Authorization header is formed correctly including the signature.
        '409':
          description: The specified account is not verified.
        '413':
          description: Request entity is too large.
        '422':
          description: One of the inputs is not valid.
        '500':
          description: The server encountered an internal error. Please retry the request.
    get:
      operationId: getAllWorks
      summary: Returns an array of all works created by the account.
      parameters:
          - in: header
            name: token
            schema:
              type: string
            required: true
      responses: 
        '200':
          description: OK
          content:
            application/json:
              schema: 
                $ref: '#/components/schemas/Works'
        '403':
          description: Server failed to authenticate the request. Make sure the value of the Authorization header is formed correctly including the signature.
        '409':
          description: The specified account is not verified.
        '500':
          description: The server encountered an internal error. Please retry the request.
  /works/{workId}:
    get:
      operationId: getWork
      summary: Returns a work by Id.
      parameters:
        - in: path
          name: workId
          schema:
            type : string
            minimum: 1
          required: true
        - in: header
          name: token
          schema:
            type: string
          required: true
      responses: 
        '200':
          description: OK
          content:
            application/json:
              schema: 
                $ref: '#/components/schemas/Work'
        '400':
          description: Work not found.
        '403':
          description: Server failed to authenticate the request. Make sure the value of the Authorization header is formed correctly including the signature.
        '409':
          description: The specified account is not verified.
        '500':
          description: The server encountered an internal error. Please retry the request.
components:
  schemas:
    Account:
      type: object
      required:
        - 'email'
        - 'password'
      properties:
        email:
          type: string
        password:
          type: string
    Profile:
      type: object
      required:
        - 'email'
        - 'createdAt'
        - 'verified'
      properties:
        email:
          type: string
        createdAt:
          type: string
        verified:
          type: boolean
    Token:
      type: string
    TokenNew:
      type: object
      properties:
        network:
          type: string
    Tokens:
      type: object
      required:
        - 'apiTokens'
      properties:
        apiTokens:
          type: array
          items:
            $ref: '#/components/schemas/Token'
    Work:
      type: 'object'
      required:
        - 'name'
        - 'datePublished'
        - 'dateCreated'
        - 'author'
        - 'content'
      properties:
        name:
          type: string
        datePublished:
          type: string
          format: date-time
        dateCreated:
          type: string
          format: date-time
        author:
          type: string
        tags:
          type: string
        content:
          type: string
    Works:
      type: 'array'
      items:
        $ref: '#/components/schemas/Work'