ranger/orm/services/region_manager/swagger/swagger.yaml

swagger: '2.0'
info:
  version: 3.5.0
  title: RMS API

# the domain of the service
host: 127.0.0.1
# array of all schemes that your API supports
schemes:
  - https

# will be prefixed to all paths
basePath: /v2/orm
produces:
  - application/json

paths:
  /regions:
    parameters:

      - $ref: "#/parameters/Client"
    post:
      summary: Create a new region
      parameters:
        - $ref: "#/parameters/Token"
        - $ref: "#/parameters/Region"
        - name: full region
          in: body
          description: input body to create full region
          schema:
            $ref: '#/definitions/RegionsData'
          required: true

      tags:
        - Region

      responses:
        201:
          description: Region created successfully
          schema:
              $ref: '#/definitions/RegionsData'
        400:
          description: Bad Request Error
          schema:
            $ref: '#/definitions/400'
        409:
          description: Duplicate Error
          schema:
            $ref: '#/definitions/409'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

    get:
      summary: get a list of regions by criteria (or all regions, if no criterion is specified)
      parameters:
        - name: type
          in: query
          type: "string"
          required: false
        - name: status
          in: query
          type: "string"
          required: false
        - name: metadata
          in: query
          type: "array"
          items:
            type: "string"
          required: false
        - name: rangerAgentVersion
          in: query
          type: "string"
          required: false
        - name: clli
          in: query
          type: "string"
          required: false
        - name: regionname
          in: query
          type: "string"
          required: false
        - name: osversion
          in: query
          type: "string"
          required: false
        - name: valet
          in: query
          type: "string"
          required: false
        - name: country
          in: query
          type: "string"
          required: false
        - name: state
          in: query
          type: "string"
          required: false
        - name: city
          in: query
          type: "string"
          required: false
        - name: street
          in: query
          type: "string"
          required: false
        - name: zip
          in: query
          type: "string"
          required: false
      tags:
        - Region
      responses:
        200:
          description: list of regions by criteria
          schema:
              $ref: '#/definitions/RegionsWrapper'
        404:
          description: No regions found for the specified criteria
          schema:
            $ref: '#/definitions/404'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

  /regions/{region_id}:
    parameters:
      - $ref: "#/parameters/Client"
    get:
      summary: Get a region by id or name
      parameters:
        - name: region_id
          in: path
          type: string
          description: ID or name of the requested region
          required: true
      tags:
        - Region
      responses:
        200:
          description: The requested region
          schema:
            $ref: '#/definitions/RegionsData'
        404:
          description: Region not found
          schema:
            $ref: '#/definitions/404'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

    delete:
      summary: Delete a region by ID
      parameters:
        - $ref: "#/parameters/Token"
        - $ref: "#/parameters/Region"
        - name: region_id
          in: path
          type: string
          description: ID of the region to delete
          required: true
      tags:
        - Region
      responses:
        204:
          description: No content
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

    put:
      summary: Update a region by ID
      parameters:
        - $ref: "#/parameters/Token"
        - $ref: "#/parameters/Region"
        - name: region_id
          in: path
          type: string
          description: ID or name of the requested region
          required: true
        - name: full region
          in: body
          description: input body to create full region
          schema:
            $ref: '#/definitions/RegionsData'
          required: true
      tags:
        - Region
      responses:
        200:
          description: The updated region
          schema:
            $ref: '#/definitions/RegionsData'
        404:
          description: Region not found
          schema:
            $ref: '#/definitions/404'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

  /groups:
    parameters:
      - $ref: "#/parameters/Client"
      - $ref: "#/parameters/Token"
      - $ref: "#/parameters/Region"
    post:
      summary: Create a new group
      parameters:
        - name: full group
          in: body
          description: input body to create full group
          schema:
            $ref: '#/definitions/Groups'
          required: true

      tags:
        - Group

      responses:
        201:
          description: Group created successfully
          schema:
              $ref: '#/definitions/Result'
        400:
          description: Bad Request Error
          schema:
            $ref: '#/definitions/400'
        409:
          description: Duplicate Error
          schema:
            $ref: '#/definitions/409'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

    get:
      summary: Get all groups
      tags:
        - Group
      responses:
        200:
          description: list of groups
          schema:
              $ref: '#/definitions/GroupsWrapper'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

  /groups/{group_id}:
    parameters:
      - $ref: "#/parameters/Client"
      - $ref: "#/parameters/Token"
      - $ref: "#/parameters/Region"
    get:
      summary: Get a single group by ID
      parameters:
        - name: group_id
          in: path
          type: string
          description: ID of the requested group
          required: true
      tags:
        - Group
      responses:
        200:
          description: The requested group
          schema:
            $ref: '#/definitions/Groups'
        404:
          description: Group not found
          schema:
            $ref: '#/definitions/404'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

    delete:
      summary: Delete a group by ID
      parameters:
        - name: group_id
          in: path
          type: string
          description: ID of the group to delete
          required: true
      tags:
        - Group
      responses:
        204:
          description: No content'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

    put:
      summary: Update a group by ID
      parameters:
        - name: group_id
          in: path
          type: string
          description: ID of the requested group
          required: true
        - name: full group
          in: body
          description: input body to update full group
          schema:
            $ref: '#/definitions/Groups'
          required: true
      tags:
        - Group
      responses:
        200:
          description: The updated group
          schema:
            $ref: '#/definitions/Result'
        404:
          description: Group not found
          schema:
            $ref: '#/definitions/404'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

  /regions/{region_id}/status:
    parameters:
      - $ref: "#/parameters/Client"
      - $ref: "#/parameters/Token"
      - $ref: "#/parameters/Region"
    put:
      summary: Update a region status
      parameters:
        - name: region_id
          in: path
          type: string
          description: ID of the requested region
          required: true
        - name: status
          in: body
          description: status JSON
          schema:
            $ref: '#/definitions/RegionStatus'
          required: true
      tags:
        - Status
      responses:
        200:
          description: The updated status
          schema:
            $ref: '#/definitions/RegionStatus'
        400:
          description: Invalid status
          schema:
            $ref: '#/definitions/400'
        404:
          description: Region not found
          schema:
            $ref: '#/definitions/404'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

  /regions/{region_id}/metadata:
    parameters:
      - $ref: "#/parameters/Client"
      - $ref: "#/parameters/Token"
      - $ref: "#/parameters/Region"
    post:
      summary: Add metadata to a region
      parameters:
        - name: region_id
          in: path
          type: string
          description: ID of the requested region
          required: true
        - name: metadata
          in: body
          description: metadata JSON
          schema:
            $ref: '#/definitions/MetadataWrapper'
          required: true
      tags:
        - Metadata
      responses:
        201:
          description: Metadata successfully added
          schema:
            $ref: '#/definitions/MetadataWrapper'
        400:
          description: Invalid JSON body
          schema:
            $ref: '#/definitions/400'
        404:
          description: Region not found
          schema:
            $ref: '#/definitions/404'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

    put:
      summary: Replace region metadata
      parameters:
        - name: region_id
          in: path
          type: string
          description: ID of the requested region
          required: true
        - name: metadata
          in: body
          description: metadata JSON
          schema:
            $ref: '#/definitions/MetadataWrapper'
          required: true
      tags:
        - Metadata
      responses:
        200:
          description: Metadata successfully replaced
          schema:
            $ref: '#/definitions/MetadataWrapper'
        400:
          description: Invalid JSON body
          schema:
            $ref: '#/definitions/400'
        404:
          description: Region not found
          schema:
            $ref: '#/definitions/404'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

    get:
      summary: Get region metadata
      parameters:
        - name: region_id
          in: path
          type: string
          description: ID of the requested region
          required: true
      tags:
        - Metadata
      responses:
        200:
          description: Region metadata
          schema:
            $ref: '#/definitions/MetadataWrapper'
        404:
          description: Region not found
          schema:
            $ref: '#/definitions/404'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

  /regions/{region_id}/metadata/{metadata_key}:
    parameters:
      - $ref: "#/parameters/Client"
      - $ref: "#/parameters/Token"
      - $ref: "#/parameters/Region"
    delete:
      summary: Delete metadata from a region
      parameters:
        - name: region_id
          in: path
          type: string
          description: ID of the requested region
          required: true
        - name: metadata_key
          in: path
          type: string
          description: Metadata key to delete
          required: true
      tags:
        - Metadata
      responses:
        204:
          description: No content
        404:
          description: Region not found
          schema:
            $ref: '#/definitions/404'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'


definitions:
  Address:
    type: object
    properties:
      country:
        type: string
      state:
        type: string
      city:
        type: string
      street:
        type: string
      zip:
        type: string

  EndPoint:
    type: object
    properties:
      publicURL:
        type: string
      type:
        type: string

  RegionsData:
    type: object
    properties:
      status:
        type: string
        enum: [
            "building",
            "functional",
            "maintenance",
            "down"
        ]
      id:
        type: string
        description: Region ID
      name:
        type: string
        description: deprecated, this field is ignored
      ranger_agent_version:
        type: string
        example: "AIC3.5"
      open_stack_version:
        type: string
      clli:
        type: string
      metadata:
        $ref: '#/definitions/ListDictionary'
      endpoints:
        type: array
        description: Region endpoints. Must include "identity", "ord" and "dashboard"
        items:
          $ref: '#/definitions/EndPoint'
      address:
        $ref: '#/definitions/Address'
      design_type:
        type: string
        example: "medium"
      location_type:
        type: string
      domain_name:
        type: string
      vlcp_name:
        type: string

  Groups:
    type: object
    properties:
      id:
        type: string
      name:
        type: string
      description:
        type: string
      regions:
        type: array
        items:
          type: string

  GroupsWrapper:
    type: object
    properties:
      groups:
        type: array
        items:
          $ref: '#/definitions/Groups'

  Result:
    type: object
    properties:
      group:
        $ref: '#/definitions/Groups'

  RegionStatus:
    type: object
    properties:
      status:
        type: string
        enum: [
            "functional",
            "maintenance",
            "building",
            "down"
        ]
      links:
        type: object
        description: Status link, for output only
        example: {"property1": "value1"}

  MetadataWrapper:
    type: object
    properties:
      metadata:
        $ref: '#/definitions/ListDictionary'

  RegionsWrapper:
    type: object
    properties:
      regions:
        type: array
        items:
          $ref: '#/definitions/RegionsData'

  Error:
    type: object
    properties:
      code:
        type: integer
        format: int32
      type:
        type: string
      transaction_id:
        type: string
      message:
        type: string
      details:
        type: string

  409:
    type: object
    properties:
      code:
        type: integer
        format: int32
      type:
        type: string
      transaction_id:
        type: string
      message:
        type: string
      details:
        type: string

  400:
    type: object
    properties:
      code:
        type: integer
        format: int32
      type:
        type: string
      transaction_id:
        type: string
      message:
        type: string
      details:
        type: string

  404:
    type: object
    properties:
      code:
        type: integer
        format: int32
      type:
        type: string
      transaction_id:
        type: string
      message:
        type: string
      details:
        type: string

  ListDictionary:
    type: object
    additionalProperties:
      type: "string"
    example: {"property1": ["value1", "value2"]}


parameters:
  Token:
    name: X-Auth-Token
    in: header
    description: Token from keystone
    required: true
    type: string

  Region:
    name: X-Auth-Region
    in: header
    description: Region
    required: true
    type: string

  Client:
    name: X-RANGER-Client
    in: header
    description: Client name
    required: false
    type: string