Device42 Patch Panels API

openapi: 3.2.0
info:
  title: Device42 Patch Panels 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: Patch Panels
paths:
  /api/1.0/patch_panel/{ID}/:
    get:
      operationId: getPatch_panelID
      summary: Get specific
      description: Retrieve detailed information about a specific Patch Panel by Patch Panel ID. This also includes end point connections
      tags:
      - Patch Panels
      parameters:
      - name: ID
        in: path
        required: true
        description: The ID of the Patch Panel to retrieve
        schema:
          type: integer
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Patch_panel'
        '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/patch_panel_port/{ID}:
    get:
      operationId: getPatchPanelPortInfo
      summary: Get specific
      description: Retrieve detailed information about a specific Patch Panel port by patch panel port ID.
      tags:
      - Patch Panels
      parameters:
      - name: ID
        in: path
        description: ID of the port
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Patch_panel_port'
        '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/patch_panel_ports/{patch_panel_id}/:
    get:
      operationId: getPatch_panel_portsPatch_panel_id
      description: Retrieves patch panel ports for specified patch panel
      summary: Get all ports
      tags:
      - Patch Panels
      parameters:
      - name: patch_panel_id
        in: path
        required: true
        description: Patch panel id
        schema:
          type: integer
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                type: array
                items:
                  properties:
                    name:
                      example: 1
                    ppport_id:
                      example: 481
        '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/patch_panel_ports/:
    post:
      operationId: postPatch_panel_portsPatch_panel_id
      summary: Update ports
      description: 'Update Patch Panel Ports. Requires the following parameters:


        patch_panel_id OR patch_panel


        number'
      tags:
      - Patch Panels
      parameters:
      - $ref: '#/components/parameters/back_connection_id'
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                patch_panel_id:
                  description: Patch panel id
                  type: string
                patch_panel:
                  description: Must be a unique asset name for this to work (Added in v5.8.2)
                  type: string
                number:
                  description: Port number for the patch panel
                  type: string
                module_slot:
                  description: 'change patch panel port for a certain module slot # (Added in v5.8.2)'
                  type: string
                mac_id:
                  description: mac_id references port_id value. mac_id available via GET at /api/api/1.0/macs/ or Tools > Export > MAC Address * Please see note below
                  type: string
                mac_address:
                  description: mac_address or hwaddress
                  type: string
                switchport_id:
                  description: ID for the switch port. Available via GET at /api/api/1.0/switchports/ or Tools > Export > Switch Port
                  type: string
                switch:
                  description: Must be used with switchport if switchport_id is not used.
                  type: string
                switchport:
                  description: Must be used with switch if switchport_id is not used.
                  type: string
                patch_panel_port_id:
                  description: Or use front_patch_panel and front_port combination
                  type: string
                front_patch_panel_id:
                  description: Name of the front patch panel - if a patch panel port is connected in front (Added in v5.8.2)
                  type: string
                front_patch_panel:
                  description: Name of the front patch panel - if a patch panel port is connected in front (Added in v5.8.2)
                  type: string
                front_port:
                  description: Number of the port on the front patch panel - if a patch panel port is connected in front (Added in v5.8.2)
                  type: string
                label:
                  type: string
                obj_label1:
                  description: object label 1
                  type: string
                obj_label2:
                  description: object label 2
                  type: string
                back_switchport_id:
                  description: Used if back connection type is switch.
                  type: string
                back_switch:
                  description: If back connection type is switch, use switch and switchport names in combination.
                  type: string
                back_switchport:
                  description: Use if back connection type is switch - use in combination with back_switch.
                  type: string
                back_patch_panel_id:
                  description: ID of the back patch panel - if a patch panel port is connected in back (Added in v5.8.2)
                  type: string
                back_patch_panel:
                  description: Name of the back patch panel - if a patch panel port is connected in back (Added in v5.8.2)
                  type: string
                back_port:
                  description: Number of the port on the back patch panel - if a patch panel port is connected in back (Added in v5.8.2)
                  type: string
                clear_front:
                  description: “yes” will clear front connection for port
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                clear_back:
                  description: “yes” will clear back connection on port
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                cable_type:
                  description: named value of the cable type. Must already exist.
                  type: string
              required:
              - number
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                type: array
                items:
                  properties:
                    msg:
                      example:
                      - patch port details edited successfully.
                      - 490
                      - 'DC1R1PP1 : 10 (testtest)'
                    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/patch_panel_models/:
    get:
      operationId: getPatch_panel_models
      description: Retrieves all patch panel models
      summary: Get all models
      parameters:
      - name: name
        in: query
        description: filter by name
        schema:
          type: string
      tags:
      - Patch Panels
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                type: array
                items:
                  properties:
                    module_position:
                      example: horizontal
                    name:
                      example: m1
                    numbering_direction:
                      example: left-right
                    numbering_start_location:
                      example: top-left
                    patch_panel_model_id:
                      example: 1
                    type:
                      example: Modular
                    type_id:
                      example: 2
        '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: postPatch_panel_models
      description: 'Create/update patch panel model. Required parameters:


        patch_panel_model_id OR name'
      summary: Create model
      tags:
      - Patch Panels
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                patch_panel_model_id:
                  description: Patch Panel Model ID or UI Tools > Export > Patch Panel Model
                  type: integer
                name:
                  description: Name of the patch panel model you want to edit or create.
                  type: string
                manufacturer:
                  description: name of the hardware/software manufacturer.
                  type: string
                type:
                  type: string
                  enum:
                  - singluar
                  - modular
                  default: singluar
                port_type:
                  description: name of the port type. created if it doesn't exist already
                  type: string
                paired_ports:
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                imgfile_id:
                  description: Image file ID.
                  type: integer
                imgfile:
                  description: name of the image file (Added in v5.8.2). Use instead of imgfile_id
                  type: string
                number_of_ports:
                  description: number of ports. required for creating a new patch panel type singular. Ignored for patch panel type modular
                  type: string
                number_of_ports_in_row:
                  description: number of ports in a row. required for creating a new patch panel type singular. Ignored for patch panel type modular
                  type: string
                module_position:
                  description: for Modular Patch Panel Models. Possible values are horizontal or vertical (Added in v5.8.2)
                  type: string
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                properties:
                  msg:
                    example:
                    - Patch Panel Model added/updated
                    - 12
                    - 48-port-ethernet
                    - true
                    - false
                  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/patch_panel_module_models/:
    get:
      operationId: getPatch_panel_module_models
      description: Retrieves all patch panel module models
      summary: Get all module models
      tags:
      - Patch Panels
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                type: array
                items:
                  properties:
                    name:
                      example: r1
                    number_of_ports:
                      example: 12
                    number_of_ports_in_row:
                      example: 6
                    patch_panel_module_model_id:
                      example: 1
                    port_type:
                      example: Fiber LC
        '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: postPatch_panel_module_models
      description: 'Create/update patch panel module model. Required parameters:


        patch_panel_module_model_id OR name'
      summary: Create/update module model
      tags:
      - Patch Panels
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                patch_panel_module_model_id:
                  description: ID of the Patch Panel Module model
                  type: integer
                name:
                  description: Name of the patch panel module model you want to edit or create.
                  type: string
                port_type:
                  description: name of the port type. created if it doesn't exist already
                  type: string
                paired_ports:
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                number_of_ports:
                  description: number of ports. required for creating a new patch panel type singular. Ignored for patch panel type modular
                  type: string
                number_of_ports_in_row:
                  description: number of ports in a row. required for creating a new patch panel type singular. Ignored for patch panel type modular
                  type: string
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                properties:
                  msg:
                    example:
                    - Patch Panel Module Model added/updated
                    - 2
                    - 6-port-module
                    - true
                    - false
                  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:
  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.
  schemas:
    Patch_panel_port:
      type: object
      properties:
        id:
          type: integer
          example: 123
        color:
          type: string
          example: '#666B61'
        object_id:
          type: integer
          example: 1235
        content_type:
          type: string
          example: patch_panel_port
        Pp_port_end:
          type: string
          example: good
        obj_label:
          type: string
          example: label
        number:
          type: integer
          example: 24
        panel_name:
          type: string
          example: Patch3
        pp_port:
          type: integer
          example: 1
        connection_id:
          type: array
          items:
            type: object
            properties:
              type:
                type: boolean
                example: false
              id:
                type: integer
                example: 1234
              patch_panel_name:
                type: string
                example: Patch4
              type_name:
                type: string
                example: patch_panel_port
              name:
                type: string
                example: Patch4 1 (To Patch3)
              patch_panel_id:
                type: integer
                example: 891
        module_id:
          type: integer
          example: 12
        full_path:
          type: string
          example: 'None <->  <a href="/admin/rackraj/patch_panel_port/123" target="_blank">AC Unit-AC101-None : 12</a> <-> None'
        cable_color:
          type: string
          example: black
    Patch_panel:
      type: object
      properties:
        asset_contracts:
          example: []
        asset_id:
          example: 29
        asset_no:
          example: '0010'
        asset_purchases:
          example: []
        building:
          example: New Haven
        custom_fields:
          example: ''
        customer_id:
          example: 1
        depth:
          example: Half Depth
        imagefile_id:
          example: 2
        name:
          example: DC1R1PP1
        no_ports:
          example: 12
        no_ports_in_row:
          example: 12
        notes:
          example: Notes, Notes, Notes...
        numbering_direction:
          example: left-right
        numbering_start_location:
          example: top-left
        orientation:
          example: Back
        patch_panel_model_id:
          example: 6
        ports:
          type: array
          items:
            properties:
              back_connection_id:
                example: 109
              back_pp_id:
                example: 16
              cable_color:
                example: black
              color:
                example: '#659a39'
              content_type:
                example: device
              device_id:
                example: 153
              device_name:
                example: USNHCTVH002
              full_path:
                example: USNHCTVH002 <-> [DC1R1PP1-29:1] <-> DC1R5PP1-109:1 <-> NHCTCORE01(gbE/1)
              number:
                example: 1
              obj_label:
                example: LI
              object_id:
                example: 153
              panel_id:
                example: 29
              panel_name:
                example: DC1R1PP1
        rack:
          example: NH-DC1-04
        rack_id:
          example: 23
        room:
          example: NHDC1
        row:
          example: 1
        serial_no:
          example: '4242424242'
        service_level:
          example: In Service
        size:
          example: 2
        start_at:
          example: 40
        type:
          example: 1
        vendor:
          example: Black Box Corp
        vendor_id:
          example: 36
        where:
          example: Rack Mounted
  parameters:
    back_connection_id:
      name: back_connection_id
      in: query
      description: ID for the back connection port. Available via GET at /api/api/1.0/patch_panel_ports// or Tools > Export > Patch Panel Port
      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.