Device42 Racks API

openapi: 3.2.0
info:
  title: Device42 Racks API
  version: '2.0'
  description: 'API Overview


    RESTful APIs are supported in Device42 as one of the primary methods of entering, editing and retrieving data.'
  contact:
    name: Device42
    email: support@device42.com
servers:
- url: https://<host>
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Racks
paths:
  /api/1.0/racks/:
    get:
      operationId: getRacks
      summary: Get all
      description: This API will retrieve basic information about all racks
      tags:
      - Racks
      parameters:
      - $ref: '#/components/parameters/name'
      - $ref: '#/components/parameters/building_id'
      - $ref: '#/components/parameters/building'
      - $ref: '#/components/parameters/room_id'
      - $ref: '#/components/parameters/room'
      - name: size
        description: filter by rack size in U
        in: query
        schema:
          type: integer
      - name: row
        description: filter by row name
        in: query
        schema:
          type: string
      - name: asset_no
        description: filter by asset number
        in: query
        schema:
          type: string
      - name: manufacturer
        description: filter by manufacturer
        in: query
        schema:
          type: string
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                properties:
                  limit:
                    example: 2
                  offset:
                    example: 0
                  racks:
                    type: array
                    items:
                      $ref: '#/components/schemas/racks'
                  total_count:
                    example: 275
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: postRacks
      description: 'Create / Update Racks. Creating a new rack requires both


        name


        size


        However, if updating a rack, use


        rack_id


        or all of


        name


        room


        building


        If using room/building name, first combination of room name or room and building name will be used.'
      summary: Create/update
      tags:
      - Racks
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                name:
                  description: Rack name - must be unique within a room
                  type: string
                size:
                  description: In UI
                  type: integer
                rack_id:
                  description: Required to update a rack using ID. This has highest priority to update a rack.
                  type: integer
                room:
                  description: Name of room - Required if changing a rack without rack_id.
                  type: string
                building:
                  description: Name of building - Used when there are non-unique room names.
                  type: string
                new_name:
                  description: Use to change name of object.
                  type: string
                room_id:
                  description: Room ID if Room name is not unique
                  type: string
                numbering_start_from_bottom:
                  description: default is yes, no to change, otherwise ignored.
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                first_number:
                  description: default 0, add to change.
                  type: string
                row:
                  description: this row field is for the name of the rows, and not related to the grid positioning of the rack
                  type: string
                manufacturer:
                  description: name of the hardware/software manufacturer.
                  type: string
                notes:
                  description: Any additional notes
                  type: string
                start_row:
                  description: Starting row for rack, for grid positioning
                  type: string
                start_col:
                  description: Starting column for the rack, for grid positioning
                  type: string
                row_size:
                  description: How many rows long the rack is
                  type: string
                col_size:
                  description: how many racks wide the rack is
                  type: string
                orientation:
                  description: 'orientation of the rack in room layout view. Possible values: right, left, up or down.'
                  type: string
                  enum:
                  - left
                  - right
                  - up
                  - down
                groups:
                  description: If multitenancy is on, admin groups that have access to this object are specified here, e.g. Prod_East:no,Corp:yes specifies that the admin groups for this object are Prod_East with view only permission and Corp with change permission. If this parameter is present with no value, all groups are deleted.
                  type: string
              required:
              - name
              - size
        required: true
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                properties:
                  msg:
                    example:
                    - rack added.
                    - 29
                    - '34'
                  code:
                    example: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/1.0/racks/{ID}/:
    get:
      operationId: getRacksID
      description: Retrieve detailed information about a specific rack including all racked devices, assets and PDUs
      summary: Get specific
      tags:
      - Racks
      parameters:
      - name: ID
        in: path
        required: true
        description: The ID of the rack to retrieve
        schema:
          type: integer
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                properties:
                  asset_no:
                    example: ''
                  assets:
                    example: []
                  available_u:
                    example: 10
                  building:
                    example: New Haven
                  custom_fields:
                    type: array
                    items:
                      properties:
                        key:
                          example: Master Key?
                        notes:
                          example: ''
                        value:
                          example: ''
                  devices:
                    type: array
                    items:
                      $ref: '#/components/schemas/RackDevices'
                  first_number:
                    example: 0
                  manufacturer:
                    example: APC Inc.
                  name:
                    example: NH-DC1-02
                  notes:
                    example: ''
                  number_between_us:
                    example: true
                  numbering_start_from_bottom:
                    example: 'yes'
                  pdus:
                    type: array
                    items:
                      properties:
                        bootstrap_power:
                          example: 0.00 W
                        depth:
                          example: Half Depth
                        file_names:
                          example:
                          - /var/www/graphics/images/apc-rack-pdu-front.png
                          - ''
                        name:
                          example: USNHCTPDU-03
                        num_ports:
                          example: '32'
                        orientation:
                          example: Back
                        pdu_id:
                          example: 16
                        power_draw:
                          example: ' '
                        reversed:
                          example: 'no'
                        size:
                          example: 1
                        start_at:
                          example: ''
                        total_ports:
                          example: 32
                        where:
                          example: Right
                        width:
                          example: 2520
                        xpos:
                          example: 0
                  rack_id:
                    example: 21
                  rack_middle_option:
                    example: Start at
                  rack_url:
                    example: /api/api/1.0/racks/21/
                  room:
                    example: NHDC1
                  row:
                    example: ''
                  row_size:
                    example: 1
                  size:
                    example: 42
                  start_col:
                    example: 29
                  start_row:
                    example: 10
                  tags:
                    example: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      operationId: deleteRacksID
      description: This API is used to delete the rack with the rack id supplied as the required argument
      summary: Delete
      tags:
      - Racks
      parameters:
      - name: ID
        in: path
        required: true
        description: rack id
        schema:
          type: integer
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                properties:
                  deleted:
                    example: 'true'
                  id:
                    example: '114'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/1.0/asset/rack/{id}/:
    delete:
      operationId: deleteAssetsRack
      summary: Remove Asset from Rack
      description: This API is used to un-rack the asset
      tags:
      - Racks
      parameters:
      - name: id
        in: path
        required: true
        description: Asset ID
        schema:
          type: integer
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                properties:
                  deleted:
                    example: 'true'
                  id:
                    example: '114'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/1.0/custom_fields/rack/:
    put:
      operationId: putCustom_fieldsRack
      description: Create or update custom fields for racks. "ID" or "name" of rack is needed even when value is not being changed
      summary: Custom fields
      tags:
      - Racks
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                name:
                  description: name of room
                  type: string
                id:
                  description: Rack ID or UI > Tools > Export > Rack
                  type: string
                key:
                  description: Can be new or existing. This is the custom field name.
                  type: string
                type:
                  description: this is the custom field type. If left blank, default is text. Date should be formatted as YYYY-MM-DD
                  type: string
                  enum:
                  - text
                  - number
                  - date
                  - related_field
                  - boolean
                  - url
                  - picklist
                  - json
                  - markup
                mandatory:
                  description: Is custom field mandatory? yes/no
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                filterable:
                  description: Is custom field filterable? yes/no
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                log_for_api:
                  description: Log custom field? yes/no
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                related_field_name:
                  description: Required if type = related_field. The existing field to relate this custom field to. Below are details for some of the fields that have been renamed or require further clarification. appcomp (for application components), businessapp (for Business Service), circuit (for Telco Circuit), cloudinfrastructure (for Cloud Account),  hardware (for device hardware model), netport (for Switch Port), organisation (for Vendor), pdu (for Power Unit), pdu_model (for Power Unit Model), purchase (for Purchase Order), software (for Software Component), vlan (for Subnet)
                  type: string
                  enum:
                  - appcomp
                  - building
                  - businessapp
                  - certificate
                  - circuit
                  - cloudinfrastructure
                  - costcenter
                  - customer
                  - device
                  - dns_zone
                  - endusers
                  - hardware
                  - ip_address
                  - netport
                  - organisation
                  - os
                  - pdu
                  - pdu_model
                  - powercircuit
                  - purchase
                  - rack
                  - room
                  - servicecategory
                  - software_category
                  - software
                  - vlan
                add_to_picklist:
                  description: Comma separated values to add to picklist. If type is picklist and custom field is new, this is a required field. Duplicates will be ignored.
                  type: string
                remove_from_picklist:
                  description: Comma separated values to be removed from picklist. Duplicates will be ignored. Values that are in use will Not be deleted, unless <b>delete_in_use</b> parameter is provided and set to <b>yes</b>
                  type: string
                delete_in_use:
                  description: pass in <b>yes</b> if you want to delete Picklist value that is in use. Used in conjunction with <b>remove_from_picklist</b>.
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                related_field_value_by_id:
                  description: Select yes if you want to set the related field value by ID.
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                value:
                  description: This will set the value of the custom field for the specific object.
                  type: string
                clear_value:
                  description: yes to clear existing value for that field
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                notes:
                  description: Any additional notes
                  type: string
                clear_notes:
                  description: Yes to clear any existing notes
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                bulk_fields:
                  description: comma separated key value pairs, with key and value separated by colon. e.g.key1:value1, key2:value2
                  type: string
                multi_select:
                  description: Applies only to Picklist fields. Is custom field multi select? yes/no
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
              required:
              - key
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                properties:
                  msg:
                    example:
                    - custom key pair values added or updated
                    - 29
                    - 34 - 12 (in 3nd Floor @ main office)
                  code:
                    example: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    RackDevices:
      type: object
      properties:
        depth:
          example: Full Depth
        device:
          type: object
          properties:
            asset_no:
              example: ''
            device_id:
              example: 215
            device_url:
              example: /api/api/1.0/devices/id/215/
            is_it_blade_host:
              example: 'no'
            is_it_switch:
              example: 'no'
            is_it_virtual_host:
              example: 'no'
            name:
              example: USNHCS-DCM06
            serial_no:
              example: ''
            type:
              example: physical
            uuid:
              example: ''
        file_names:
          example:
          - /var/www/graphics/images/HP--ProLiant-DL380p-Gen8.png
          - /var/www/graphics/images/HP--ProLiant-DL380p-Gen8-B.png
        orientation:
          example: Front
        reversed:
          example: 'no'
        size:
          example: 2
        start_at:
          example: 1
        where:
          example: Rack Mounted
        width:
          example: 2520
        xpos:
          example: 0
    racks:
      type: object
      properties:
        asset_no:
          example: ''
        available_u:
          example: 45
        building:
          example: Building
        col_size:
          example: 1
        custom_fields:
          example: []
        first_number:
          example: 1
        groups:
          example: ''
        manufacturer:
          example: APC Inc.
        name:
          example: RA1
        notes:
          example: ''
        number_between_us:
          example: true
        numbering_start_from_bottom:
          example: 'yes'
        rack_id:
          example: 255
        rack_middle_option:
          example: End at
        rack_url:
          example: /api/api/1.0/racks/255/
        room:
          example: Main room
        row:
          example: ''
        row_size:
          example: 1
        size:
          example: '45'
        start_col:
          example: 4
        start_row:
          example: 2
        tags:
          example: []
  responses:
    Forbidden:
      description: Forbidden (The resource requested is hidden)
      content:
        application/json:
          example:
            errors:
            - code: 403
              reason: Forbidden
              title: Forbidden
              detail: The resource requested is hidden
    BadRequest:
      description: Bad Request (A validation exception has occurred.)
      content:
        application/json:
          example:
            errors:
            - code: 400
              reason: BAD_REQUEST
              title: The error response code title.
              detail: Details of the error response.
    Unauthorized:
      description: Unauthorized (Invalid credentials.)
      content:
        application/json:
          example:
            errors:
            - code: 401
              reason: Unauthorized
              title: Unauthorized
              detail: Invalid credentials.
    InternalServerError:
      description: Internal Server Error (A required parameter is missing or there is an issue with the server. Check the returned 'msg' field from the call.)
      content:
        application/json:
          example:
            errors:
            - code: 500
              reason: Internal Server Error
              title: Internal Server Error
              detail: A required parameter is missing or there is an issue with the server. Check the returned 'msg' field from the call.
    NotFound:
      description: Not Found (The specified resource could not be found)
      content:
        application/json:
          example:
            errors:
            - code: 404
              reason: Not Found
              title: Not Found
              detail: The specified resource could not be found.
    ServiceUnavailable:
      description: Service Unavailable (Please check if your Device42 instance is working normally.)
      content:
        application/json:
          example:
            errors:
            - code: 503
              reason: Service Unavailable
              title: Service Unavailable
              detail: Please check if your Device42 instance is working normally.
  parameters:
    building:
      name: building
      in: query
      description: filter by building name
      schema:
        type: string
    name:
      name: name
      in: query
      description: filter by name (Added in v6.0.0)
      schema:
        type: string
    building_id:
      name: building_id
      in: query
      description: filter by building ID (Added in v5.9.0)
      schema:
        type: integer
    room_id:
      name: room_id
      in: query
      description: filter by room ID (Added in v5.9.0)
      schema:
        type: integer
    room:
      name: room
      in: query
      description: filter by room name. Only works if room ID is not present (Added in v5.9.0)
      schema:
        type: string
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication using a Device42 user's username and password.
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token obtained from POST /tauth/1.0/token/ using an API Client's key/secret as Basic auth credentials.