reshapr-admin-ctrl-openapi-v0.1.yaml

---
openapi: 3.0.2
info:
  title: reShapr Admin Ctrl API v0.1
  version: 0.0.1
  description: reShapr control place administration REST API
  contact:
    name: Laurent Broudoux
    url: https://github.com/lbroudoux
    email: laurent.broudoux@gmail.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
paths:
  /admin/users:
    get:
      operationId: getUsers
      summary: Get the list of all registered users
      parameters:
        - name: page
          in: query
          description: Page number (starting from 0)
          required: false
          schema:
            type: integer
            default: 0
        - name: size
          in: query
          description: Page size
          required: false
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserView'
      security:
        - admin-api-key: []
    post:
      operationId: createUser
      summary: Create a new user
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserRequest'
        required: true
      responses:
        "201":
          description: The User has been registered in control plane
        "409":
          description: A User with this username already exist
      security:
        - admin-api-key: [ ]

  /admin/users/{username}/organization:
    post:
      requestBody:
        description: The organization to create
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationRequest'
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationRequest'
          description: The organization has been created and is owned by user
        "409":
          description: An organization with this name already exist
        "404":
          description: The User with this name is unknown
      security:
      - admin-api-key: []
      operationId: createUserOwnedOrganization
    parameters:
    - name: username
      description: The unique username of user to manage organization for
      schema:
        type: string
      in: path
      required: true
  /admin/users/{username}/organization/{organizationName}:
    put:
      requestBody:
        description: The new information to update organization
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationRequest'
          description: Organization has been updated
        "404":
          description: The user with name is unknown
      operationId: updateOrganization
    parameters:
    - name: username
      description: The unique username of user to manage organization for
      schema:
        type: string
      in: path
      required: true
    - name: organizationName
      description: The unique name of organization
      schema:
        type: string
      in: path
      required: true
  /admin/users/{username}/organization/{organizationName}/owner:
    put:
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
          description: User has been assigned as organization owner
      security:
        - admin-api-key: [ ]
      operationId: updateOrganizationOwner
    parameters:
      - name: username
        description: The unique username of user to manage organization for
        in: path
        required: true
      - name: organizationName
        description: The unique username of organization
        in: path
        required: true
  /admin/users/{username}/memberships:
    put:
      requestBody:
        description: The list of organization names to assign user as member
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
          description: User has been assigned as member of this organizations. Return
            the list of names.
        "404":
          description: The user with proivide dname is unknown
      security:
      - admin-api-key: []
      operationId: assignMemberships
    parameters:
    - name: username
      description: The name of user to manage memberships for
      in: path
      required: true
  /admin/organizations:
    get:
      operationId: getOrganizations
      summary: Get the list of all organizations in control plane
      parameters:
        - name: page
          in: query
          description: The page number to retrieve (0-based)
          schema:
            type: integer
            default: 0
        - name: size
          in: query
          description: The number of items per page
          schema:
            type: integer
            default: 20
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Organization'
          description: The list of organizations in control plane
      security:
        - admin-api-key: []
    post:
      operationId: createOrganization
      summary: Create a new organization without assigning owner
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationRequest'
        required: true
      responses:
        "201":
          description: Organization has been created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationRequest'
        "409":
          description: Organization with this name already exist
      security:
        - admin-api-key: []
  /admin/organizations/{organizationName}/owner:
    put:
      operationId: updateOrganizationOwner
      summary: Update the owner of an organization
      parameters:
        - name: organizationName
          in: path
          description: The unique name of organization to update owner for
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: string
              description: The unique username of user to assign as owner
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
          description: User has been assigned as organization owner
        "404":
          description: The user with name is unknown or organization with name is unknown
      security:
        - admin-api-key: []
  /admin/quotas/organization/{organizationName}:
    get:
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Quota'
          description: The list of quotas applied to this organization
        "404":
          description: The organization with this name is unknown
      security:
      - admin-api-key: []
      operationId: getOrganizatoinQuotas
    post:
      requestBody:
        description: The list of quotas to apply to organization
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/QuotaRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Quota'
          description: The list of effectively applied quotas to the organization
        "404":
          description: The organization with this name is unknown
      security:
      - admin-api-key: []
      operationId: setOrganizationQuotas
    parameters:
    - name: organizationName
      description: The name of organization to manage quotas for
      schema:
        type: string
      in: path
      required: true
  /admin/quotas/organization/{organizationName}/force:
    post:
      requestBody:
        description: The list of forced complete quota requests
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/FullQuotaRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Quota'
          description: The current quota of the organization after application
        "404":
          description: The organization with this name is unknown
      security:
      - admin-api-key: []
      operationId: forceOrganizationQuotas
      summary: Force setting remaining to limit of metric quota
    parameters:
    - name: organizationName
      description: The organization name to managed quotas for
      schema:
        type: string
      in: path
      required: true
  /admin/tokens/apiTokens/{organisationName}:
    get:
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiToken'
          description: The list of ApiToken owned by this organization
      security:
      - admin-api-key: []
      operationId: getApiTokens
    parameters:
    - name: organisationName
      description: The name of the organization to manage tokens for
      schema:
        type: string
      in: path
      required: true
components:
  schemas:
    UserRequest:
      description: Basic information for creating a User in control plane
      required:
      - username
      - email
      type: object
      properties:
        username:
          description: The user username
          type: string
        email:
          description: The user email
          type: string
        password:
          description: The user password (only if authentication is done by control
            plane)
          type: string
        firstname:
          description: The user firstname
          type: string
        lastname:
          description: The user lastname
          type: string
    UserView:
      description: A registered user in control plane
      type: object
      required:
        - username
        - email
      properties:
        username:
          description: The user username
          type: string
        email:
          description: The user email
          type: string
        firstname:
          description: The user firstname
          type: string
        lastname:
          description: The user lastname
          type: string
        defaultOrganizationName:
          description: The default organization of the user
          type: string
    Organization:
      description: An organization within the control plane
      type: object
      allOf:
      - type: object
        properties:
          ownerUsername:
            type: string
            description: The User owning this organization
      - $ref: '#/components/schemas/OrganizationRequest'
    Quota:
      description: A quota that defines limits on the usage of a specific metric for
        an organization.
      type: object
      allOf:
      - required:
        - id
        - organizationId
        type: object
        properties:
          id:
            description: The unique identifier of the quota value
            type: string
          organizationId:
            description: The unique identifier of the organization subject to this
              quota
            type: string
          remaining:
            format: int64
            description: The remanining intance of metric within this quota
            type: integer
      - $ref: '#/components/schemas/QuotaRequest'
    QuotaRequest:
      description: A quota that defines limits on the usage of a specific metric for
        an organization.
      required:
      - metric
      - enabled
      - limit
      type: object
      properties:
        metric:
          description: The metric subject to quota
          type: string
        enabled:
          description: Whether quota is enabled for this metric
          type: boolean
        limit:
          format: int64
          description: The maximum number of instance of this metric that is allowed
          type: integer
    FullQuotaRequest:
      description: A complete quota request with the remaning being set
      type: object
      allOf:
      - required:
        - remaining
        type: object
        properties:
          remaining:
            format: int64
            description: The remaining instance of that quota metric
            type: integer
      - $ref: '#/components/schemas/QuotaRequest'
    ApiToken:
      description: An API Token that allows connecting Gateways to the control plane
      required:
      - id
      - organizationId
      - name
      - token
      - validUntil
      - username
      type: object
      properties:
        id:
          description: Unique identifier of this token
          type: string
        organizationId:
          description: Unique id of the organization owning the token
          type: string
        name:
          description: Name of this token
          type: string
        token:
          description: This token string value
          type: string
        validUntil:
          format: date-time
          description: End of validity date of this token
          type: string
        username:
          description: The name of the user that has issued the token
          type: string
    OrganizationRequest:
      description: Basic information for creating an Organization in control plane
      required:
      - name
      type: object
      properties:
        name:
          description: The organization name
          maxLength: 100
          pattern: "^[a-zA-Z0-9_]*$"
          type: string
        description:
          description: The organization description
          maxLength: 255
          type: string
        icon:
          description: The organization icon (can be a URL or a base64 encoded string)
          type: string
  securitySchemes:
    admin-api-key:
      type: apiKey
      description: Control plane administration API key transferred as HTTP header
      name: x-reshapr-api-key
      in: header