openapi: 3.0.0
info:
  version: v1
  title: Roles API
  description: Use the Roles API to manage NGINX Controller User Roles.
servers:
  - description: NGINX Controller API
    url: 'https://{{CONTROLLER_FQDN}}/api/v1'
paths:
  /platform/roles:
    get:
      tags:
        - Roles
      summary: List Roles
      description: Returns an unfiltered list of all Role resources.
      operationId: getRoles
      responses:
        '200':
          description: >
            Successfully retrieved a list of all of the Role
            resources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleListResponse'
              example:
                items:
                  - currentStatus:
                      permissions:
                        - access: FULL
                          path: /
                    desiredState:
                      permissions:
                        - access: FULL
                          path: /
                    metadata:
                      createTime: '2020-02-24T21:29:59.866708Z'
                      kind: role
                      name: admin
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/Internal'
    post:
      tags:
        - Roles
      summary: Create a Role
      description: Creates a new Role resource.
      operationId: createRole
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Role'
            example:
              desiredState:
                permissions:
                  - access: READ
                    path: /services/environments/dev/
                  - access: WRITE
                    path: /services/environments/test/
              metadata:
                kind: role
                name: role1
                tags:
                  - dev
                  - test
      responses:
        '201':
          description: |
            Successfully created the requested Role resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
              example:
                currentStatus:
                  permissions:
                    - access: READ
                      path: /services/environments/dev/
                    - access: WRITE
                      path: /services/environments/test/
                desiredState:
                  permissions:
                    - access: READ
                      path: /services/environments/dev/
                    - access: WRITE
                      path: /services/environments/test/
                metadata:
                  createTime: '2020-02-24T22:55:51.729272Z'
                  kind: role
                  name: role1
                  tags:
                    - dev
                    - test
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/Internal'
  '/platform/roles/{roleName}':
    get:
      tags:
        - Roles
      summary: Get a Role
      description: >
        Returns information about a specific Role resource by its
        name.
      operationId: getRoleByName
      parameters:
        - $ref: '#/components/parameters/roleName'
      responses:
        '200':
          description: |
            Successfully retrieved the requested Role resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
              example:
                currentStatus:
                  permissions:
                    - access: READ
                      path: /services/environments/test/
                    - access: WRITE
                      path: /services/environments/dev/
                desiredState:
                  permissions:
                    - access: READ
                      path: /services/environments/test/
                    - access: WRITE
                      path: /services/environments/dev/
                metadata:
                  createTime: '2020-02-24T22:38:33.842929Z'
                  kind: role
                  name: role1
                  tags:
                    - dev
                    - test
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/Internal'
    put:
      tags:
        - Roles
      summary: Upsert a Role
      description: >
        Creates a new Role resource or updates an existing Role
        resource.
      operationId: upsertRole
      parameters:
        - $ref: '#/components/parameters/roleName'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Role'
            example:
              desiredState:
                permissions:
                  - access: WRITE
                    path: /services/environments/dev/
              metadata:
                kind: role
                name: role1
                tags:
                  - dev
                  - test
      responses:
        '200':
          description: |
            Successfully updated the specified Role resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
              example:
                currentStatus:
                  permissions:
                    - access: WRITE
                      path: /services/environments/dev/
                desiredState:
                  permissions:
                    - access: WRITE
                      path: /services/environments/dev/
                metadata:
                  createTime: '2020-02-24T22:38:33.842929Z'
                  kind: role
                  name: role1
                  updateTime: '2020-02-24T22:53:14.340686Z'
                  tags:
                    - dev
                    - test
        '201':
          description: |
            Successfully created the specified Role resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
              example:
                currentStatus:
                  permissions:
                    - access: WRITE
                      path: /services/environments/dev/
                desiredState:
                  permissions:
                    - access: WRITE
                      path: /services/environments/dev/
                metadata:
                  createTime: '2020-02-24T22:38:33.842929Z'
                  kind: role
                  name: role1
                  updateTime: '2020-02-24T22:53:14.340686Z'
                  tags:
                    - dev
                    - test
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/Internal'
    delete:
      tags:
        - Roles
      summary: Delete a Role
      description: Deletes a specific Role resource.
      operationId: deleteRole
      parameters:
        - $ref: '#/components/parameters/roleName'
      responses:
        '204':
          description: >-
            Successfully deleted the role. No content was
            returned.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/Internal'
components:
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: session
  parameters:
    roleName:
      in: path
      name: roleName
      schema:
        type: string
      required: true
      description: |
        The name of the Role.
  responses:
    BadRequest:
      description: >
        Bad input parameter, or possibly a bad URI. Check the
        input for typos and try again.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorModel'
          example:
            code: 100
            details:
              - description: >
                  Request body has an error: doesn't match the
                  schema: Error at
                  "/desiredState/permissions/0/access":JSON value
                  is not one of the allowed values

                  Schema:
                    {
                      "enum": [
                        "NONE",
                        "READ",
                        "WRITE",
                        "FULL"
                      ],
                      "type": "string"
                    }

                  Value:
                    "DELETE"
            message: Failed to validate Request
    Unauthorized:
      description: |
        User authentication is invalid or missing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorModel'
          example:
            code: 401
            message: authentication needed
    Forbidden:
      description: |
        The request failed due to insufficient privileges.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorModel'
          example:
            code: 403
            message: unauthorized
    Internal:
      description: >
        The request cannot be processed because of an internal
        server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorModel'
          example:
            code: 8913
            message: Failed to add permissions to database.
    NotFound:
      description: |
        The specified Role was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorModel'
          example:
            code: 8920
            message: 'Error getting or deleting role: role not found.'
    Conflict:
      description: >
        The request failed due to a conflict with an existing
        Role, Group, or User resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorModel'
          example:
            code: 8919
            message: 'Error creating role: role already exists.'
  schemas:
    RoleListResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Role'
          description: |
            Contains list of Role objects.
    Role:
      type: object
      required:
        - metadata
        - desiredState
      properties:
        metadata:
          $ref: '#/components/schemas/ResourceMeta'
        desiredState:
          $ref: '#/components/schemas/RoleDef'
        currentStatus:
          $ref: '#/components/schemas/RoleDef'
    RoleDef:
      type: object
      required:
        - permissions
      description: >
        A Role is a collection of permissions and child Roles. All
        Roles are globally unique. You can assign Roles to users
        or to other Roles.
      properties:
        permissions:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/Permission'
    Permission:
      type: object
      required:
        - access
        - path
      description: >
        A Permission is a pair consisting of a path or object and
        the desired level of access. Permissions govern Users
        ability to access specific paths or objects within an
        Environment.
      properties:
        path:
          type: string
          example: /services/environments/dev/
          pattern: '^(\/[^A-Z\s\x00-\x1f\x60\x7f\;\"\[\]\{\}\\\/]*)+'
          description: >
            The path represents an area of the platform to which
            the Role grants access. For example, to allow the Role
            to access an Environment named "dev", you would define
            the path "/services/environments/dev".
        access:
          type: string
          enum:
            - NONE
            - READ
            - WRITE
            - FULL
          description: >
            Access determines the Role's ability to access a path
            or object. The options are:

            * NONE: Does not have any access to the path or object

            * READ: Has read only access (HTTP GET requests)

            * WRITE: Has read and write access (POST, PUT, PATCH
            requests) but cannot delete

            * FULL: Has read, write and delete access
    SelfLinks:
      type: object
      description: >
        The SelfLinks object contains a link from the resource to
        itself.

        This object is used only in responses.
      properties:
        rel:
          type: string
          example: /api/v1/services/environments/prod
          description: >
            `rel` contains the complete path fragment of a URI and
            can be used

            to construct a query to the object.
    ResourceMeta:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          pattern: >-
            ^[^A-Z\s\x00-\x1f\x60\x7f\;\*\"\[\]\{\}\\\/%\?:=&\~\^|#<>]+$
          not:
            type: string
            enum:
              - .
              - ..
          minLength: 1
          maxLength: 1024
          example: resource-name
          description: >
            Resource name is a unique identifier for a resource
            within the context of a namespace.

            Resource names must conform to [RFC 1738 Section
            2.2](https://www.ietf.org/rfc/rfc1738.txt) and have a
            valid syntax for email addresses. The following rules
            are enforced:


            - do not utilize URL encoding;

            - do not include spaces;

            - do not use uppercase characters, for example, 'A-Z';
            extended character sets are supported;

            - do not use the following characters: `"`, `*`, `:`,
            `;`, `/`, `\`, `%`, `?`, `hash`, `=`, `&`, `|`, `~`,
            `^`, `{`, `}`, `[`, `]`, `<`, `>`;

            - cannot start or end with an `@` sign;

            - cannot be only `.` or `..`


            For example: For a collection resource located at


            `https://controller.example.com/api/v1/services/apps/shopping_@1`


            the resource name is "shopping_@1".
        displayName:
          type: string
          example: My Display Name
          description: >
            `displayName` is a user friendly resource name. It can
            be used to define 

            a longer, and less constrained, name for a resource.


            Display names:


            - are optional (defaults to an empty string if no
            value is provided),

            - do not have to be unique, 

            - cannot be assigned by the server.
        description:
          type: string
          example: >-
            This is a sample description string. It provides
            information about the resource.
          description: >
            `description` is a free-form text property. You can
            use it to provide information that helps 

            to identify the resource.


            Descriptions:


            - are optional (defaults to an empty string if no
            value is provided),

            - do not have to be unique, 

            - cannot be assigned by the server.
        kind:
          type: string
          example: <collection>-<object>
          description: >
            Kind is a string representation of an API resource's
            data type.

            It is assigned by the server and cannot be changed. 


            When creating a `kind`, the server uses hyphens to
            connect word segments; 

            singleton and collection item resources are not
            pluralized.
        uid:
          type: string
          format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
          description: >
            Unique Identifier (UID)


            UID is a unique identifier in time and space for a
            resource. 

            When you create a resource, the server assigns a UID
            to the resource.


            Refer to [IETF RFC
            4122](https://tools.ietf.org/html/rfc4122) for more
            information.
        tags:
          type: array
          items:
            type: string
          example:
            - production_public
            - dev
            - new_app
            - us-west-1
            - emea
          description: >
            You can assign `tags` to a resource as a way to help
            map, scope, 

            and organize resources. 


            The system uses tag selectors to specify selection
            criteria that 

            match resources that have particular tags.
        ref:
          type: string
          example: /services/environments/prod
          description: >
            The `ref` field contains a reference to another NGINX
            Controller resource.
        links:
          $ref: '#/components/schemas/SelfLinks'
        createTime:
          type: string
          format: date-time
          example: '2019-07-29T09:12:33.001Z'
          description: >
            A timestamp that represents the server time when the
            resource was created.


            Create time is not guaranteed to be set in
            "happens-before" order

            across separate operations.


            In JSON format, `create_time` type is encoded as a
            string in the

            [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt).


            For example: 2018-04-01T01:30:15.01Z


            Create Time is assigned by the server and cannot be
            changed.
        updateTime:
          type: string
          format: date-time
          example: '2019-07-29T10:12:33.001Z'
          description: >
            A timestamp that represents the server time when the
            resource was last modified.


            Resources that have never been updated do not have an
            `update_time` stamp.


            The default value for resources that have never been
            updated is the local 

            language-specific equivalent of "null".


            In JSON format, `update_time` type is encoded as a
            string as described in 

            [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt).
    ErrorDetail:
      type: object
      required:
        - description
      properties:
        description:
          type: string
          example: >-
            Error doing <action>: <reason for error>. This can
            lead to <potential consequences>. Try <action> to
            resolve the issue.
          description: >
            A detailed error message returned by the server. 


            These messages contain the following information,
            where applicable:


            - What happened.

            - Why it happened.

            - What the consequences are (if any).

            - Recommended action to take to resolve the issue.
    ErrorModel:
      type: object
      required:
        - message
        - code
      properties:
        message:
          type: string
          example: Error doing <action>.
          description: >
            A human-readable message, in English, that describes
            the error.
        code:
          type: integer
          example: 1234567
          description: >
            A numeric error code that can be used to identify
            errors for support purposes.
        details:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'