openapi.yml

openapi: 3.0.3

info:
  version: 1.0.0
  title: appdoki API
  description: REST API server for Cloudoki's appdoki
  license:
    name: MIT

servers:
  - url: https://appdokiapi.cloudoki.com

tags:
  - name: home
    description: Basic API information
  - name: users
    description: User related endpoints and operations
  - name: beers
    description: Beer exchanges and logs
  - name: authentication
    description: Authentication & OIDC related endpoints

paths:
  /:
    get:
      tags: [ home ]
      description: API home
      responses:
        '200':
          description: API basic information
          content:
            application/json:
              schema:
                type: object
                properties:
                  Version:
                    type: string
                  DocsEndpoint:
                    type: string
                  MessagingTopics:
                    type: array
                    items:
                      type: object
                      properties:
                        Topic:
                          type: string
                        Description:
                          type: string
  /users:
    get:
      tags: [ users ]
      description: Lists all users
      security:
        - bearerAuth: [ ]
      parameters:
        - $ref: '#/components/parameters/platformHeader'
      responses:
        '200':
          description: User model list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '500':
          $ref: '#/components/responses/Internal'
  /users/{id}:
    get:
      tags: [ users ]
      description: Returns a user based on the ID
      security:
        - bearerAuth: [ ]
      parameters:
        - $ref: '#/components/parameters/platformHeader'
        - name: id
          in: path
          description: ID of user to fetch
          required: true
          schema:
            type: number
      responses:
        '200':
          description: User model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/Internal'
  /users/{id}/beers:
    get:
      tags: [ users ]
      description: Returns a simple beer report for a user
      security:
        - bearerAuth: [ ]
      parameters:
        - $ref: '#/components/parameters/platformHeader'
        - name: id
          in: path
          description: ID of user to fetch
          required: true
          schema:
            type: number
      responses:
        '200':
          description: User beer report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserBeerLog'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/Internal'
  /users/{id}/beers/{beers}:
    post:
      tags: [ users ]
      description: Give this man some beers!
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/platformHeader'
        - in: path
          name: id
          schema:
            type: integer
          required: true
          description: Numeric ID of the user receiving beers
        - in: path
          name: beers
          schema:
            type: integer
            minimum: 1
          required: true
          description: Amount of beers
      responses:
        '204':
          description: Beers given! Thanks
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/Internal'
  /beers:
    get:
      tags: [ beers ]
      description: Returns the beer transfers feed
      security:
        - bearerAuth: [ ]
      parameters:
        - $ref: '#/components/parameters/platformHeader'
        - name: limit
          in: query
          description: Number of records to return.
          schema:
            type: number
            default: 20
        - name: op
          in: query
          description: Comparison operator for the pagination.
          schema:
            type: string
            enum: [ lt, gt ]
            default: gt
        - name: givenAt
          in: query
          description: GivenAt timestamp used for pagination. Defaults to current timestamp.
          schema:
            type: string
      responses:
        '200':
          description: Beer log
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeerTransferFeed'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/Internal'
  /auth/url:
    get:
      tags: [ authentication ]
      description: Returns the URL for the OAuth 2.0 provider's consent page
      responses:
        '200':
          description: User model list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OAuthURL'
  /auth/token:
    post:
      tags: [ authentication ]
      description: Exchange OAuth 2.0 authentication code for an access token
      responses:
        '200':
          description: ID Token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
  /auth/user:
    get:
      tags: [ authentication ]
      description: Creates a new user if not existing yet
      security:
        - bearerAuth: [ ]
      parameters:
        - $ref: '#/components/parameters/platformHeader'
      responses:
        '200':
          description: User model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    Token:
      type: object
      properties:
        token:
          type: string
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
        picture:
          type: string
    UserBeerLog:
      type: object
      properties:
        given:
          type: number
        received:
          type: number
    BeerTransferFeed:
      type: array
      items:
        type: object
        properties:
          id:
            type: number
          giver:
            $ref: '#/components/schemas/User'
          receiver:
            $ref: '#/components/schemas/User'
          givenAt:
            type: string
            format: date-time
          beers:
            type: number
    OAuthURL:
      type: object
      properties:
        url:
          type: string
          format: uri
    Error:
      type: object
      required:
        - errors
      properties:
        errors:
          type: array
          items:
            type: string

  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: Resource conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Internal:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  parameters:
    platformHeader:
      name: platform
      in: header
      description: Platorm identifying header
      required: true
      schema:
        type: string
        enum: [ web, ios, android ]
        default: web

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT