sonic_api.yaml

#
# Current rules
# 1. All requests are sync.
#
# responses:
# post:
#   201 - Created
#   400 - Bad Request. Malformed arguments for API call
#   401 - Unauthorized.  Invalid authentication credentials 
#   403 - Forbidden (capacity isssues)
#   404 - Object is not found
#   409 - Conflict. Request cannot be completed due to conflict with current state of target resource. 
#   500 - Internal Server Error
#   503 - Service Unavailable
# patch:
#   207 - Multi-Status. Consult object body to determine status on a per element basis for the Bulk API.
#   400 - Bad Request. Malformed arguments for API call
#   401 - Unauthorized.  Invalid authentication credentials 
#   403 - Forbidden (capacity isssues)
#   404 - Object is not found
#   500 - Internal Server Error
#   503 - Service Unavailable
# get:
#   200 - OK
#   400 - Bad Request. Malformed arguments for API call
#   401 - Unauthorized.  Invalid authentication credentials
#   404 - Object is not found
#   500 - Internal Server Error
#   503 - Service Unavailable
# delete:
#   200 - OK
#   204 - No Content
#   207 - Multi-Status. Consult object body to determine status on a per element basis for the Bulk API.
#   400 - Bad Request. Malformed arguments for API call
#   401 - Unauthorized.  Invalid authentication credentials
#   404 - Object is not found
#   409 - Conflict. Request cannot be completed due to conflict with current state of target resource. 
#   500 - Internal Server Error
#   503 - Service Unavailable
#
# dictionary:
#   vnet_id
#   vnid
#   vlan_id
#   ip_prefix
#   ip_addr
#
# SONiC REST API v1. Defines API for controlling data path on the SONiC TOR for Baremetal scenarios.
# Baremetal scenario description:
# Every "baremetal server" port is connected to one baremetal server. Baremetals that reside on 
# the same subnet+vnet are defined to be on a particular vlan interface. The vlan interface acts
# as the gateway and as such must be programmed with the gateway IP. Traffic inbound/outbound
# from the TOR is via a VxLAN tunnel. Customer separation is provided using Vnet, vrf and unique vxlan vnid.
#
# Our dataplane is designed as follow
# 1. We have virtual routers which represents a "virtual network" for a customer. Virtual networks are
#    defined using a string vnet_id, this internally creates a virtual router to maintain separate routing/forwarding domain.
#    The virtual routers are used to bind the customer's unique vnid and customer's local baremetal device ports
#    and as a result provide Virtual Network connectivity with the rest of Azure
# 2. We have a virtual routing table which is unique and separated for every virtual router.
# 3. We have tunnels which represent "Azure" next hops for virtual routing tables.
# 4. We have vlan specific APIs to define parameters for client ports
#
# POST Requests:
# REST API creation(POST) dependency list:
# 1. VxLAN VTEP: /config/tunnel/decap/vxlan OR Day 0 configuration. No dependency. 
# 2. Vrouter/VNET: /config/vrouter/{vnet_id} depends on 1(VxLAN VTEP)
# 3. VLAN: /config/interface/vlan Depends on 2(VNET) if vlan needs association to vrf/vnet
# 4. Vlan member: /config/interface/vlan/{vlan_id}/member Depends on 3(VLAN)
# 5. Vlan Neighbor: /config/interface/vlan/{vlan_id}/neighbor Depends on 3(VLAN)
# 6. Vrouter/VNET Routes: /config/vrouter/{vnet_id}/routes depends on 2(VNET)
#
# DELETE Requests:
# All children/dependent elements must be deleted prior to deleting any parent config elements
# This is required for data integrity and sanity of DBs.
# eg: Vlan Neighbors and Vlan members should be deleted before deleting the Vlan itself 
# REST API deletion(DELETE) dependency list:
# 1. Vrouter/VNET Routes: /config/vrouter/{vnet_id}/routes. No dependency
# 2. Vlan Neighbor: /config/interface/vlan/{vlan_id}/neighbor. No dependency
# 3. Vlan member: /config/interface/vlan/{vlan_id}/member. No dependency
# 4. VLAN: /config/interface/vlan Depends on 2(VNET). Dependes on successful deletion on all child elements 2(Vlan Neighbor) and 3(Vlan member)
# 5. Vrouter/VNET: /config/vrouter/{vnet_id}. Depends on successful deletion of all child elements 4(Vlan) and 1(Routes)
# 6. VxLAN VTEP: /config/tunnel/decap/vxlan. Depends on successful deletion of all child elements 5(VRF/VNET)
#
# Some details about '40X' error responses:
# - '400' http error returns when there're one or more malformed arguments (wrong type, format, size) in the request.
# - '404' http error returns when there're one or more references to non-existent values in the request.
# - '409' HTTP Request cannot be completed due to conflict with current state of target resource:
#       - Error sub-code 0: Conflict because the resource already exists
#       - Error sub-code 1: Conflict because of a missing dependency/parent
#       - Error sub-code 2: Conflict because the caller tries to delete a resource with a dependency/child
#       - Error format:     '#/definitions/Error'
# In case of bulk API (vroute API):
# - If a request has a malformed argument (arguments) or a reference (references) to non-existent values
#   in its path the API must return '400' or '404' respectively.
# - if a request has the same error in the attributes of the request, the API must:
#    - run the request with the valid attributes
#    - return '207' http status code to inform the caller to look within the body to confirm success/failure
#      for each of the routes
#    - put malformed attributes into the list of 'failed' attributes.
 


swagger: '2.0'
info:
  title: SONiC REST API
  description: SONiC REST API for Baremetal Scenarios
  version: 1.0.0
schemes:
  - http
  - https
basePath: /v1
produces:
  - application/json
consumes:
  - application/json
paths:
#----------------------------------------------
# Server level API
#----------------------------------------------
  '/state/heartbeat':
    get:
      summary: the heartbeat API for caller to check the status of the server
      description: Returns Ok when server is live. Also returns API version, config reset time info of the server and available routes.
      responses:
        '200':
          description: OK
          schema:
            type: object
            required:
              - server_version
              - reset_GUID
              - reset_time
              - routes_available
            properties:
              server_version:
                type: string
                description: version of the restful server.
              reset_GUID:
                type: string
                description: a GUID which will change after each time server restart from scratch.
              reset_time:
                type: string
                format: date-time
                description: time of server restartting from scratch, in a human readable format.
              routes_available:
                type: int
                description: Remaining routes available to be programmed. Returns -1 if CRM:STATS is unavailable. Continue programming routes and check back later. 
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
#----------------------------------------------
# Config Reset Status API
#----------------------------------------------
  '/config/resetstatus':
    get:
      summary: API for caller to check the status of the config in the DB
      description: Returns a JSON response with the config reset status
      responses:
        '200':
          description: OK
          schema:
            type: object
            required:
              - reset_status
            properties:
              reset_status:
                type: string
                description: configuration reset status.
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
    post:
      summary: API for caller to set the status of the config in the DB
      description: Returns a JSON response with the config reset status after the change
      parameters:
        - name: reset_status
          in: body
          required: true
          type: string
          description: The value of configuration reset status. Only true or false accepted
      responses:
        '200':
          description: OK
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
#----------------------------------------------
# Operations
#----------------------------------------------
  '/operations/ping':
    post:
      summary: pings an ip address from a VRF context, if provided
      description: Returns a JSON response object with packets transmitted, received, maxRTT, minRTT, avgRTT. When specified vnet_id doesn't exist in the config_db, returns 404 Object not found.
      parameters:
        - name: ip_address
          in: body
          required: true
          type: string
          description: IP address of the device to ping
        - name: vnet_id
          in: body
          required: false
          type: string
          description: vnet_id containing the vnet guid as a string
        - name: count
          in: body
          required: false
          type: string
          description: value for -c parameter of ping
      responses:
        '200':
          description: OK
        '404':
          description: Object not found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
#----------------------------------------------
# Virtual router object
#----------------------------------------------
  '/config/vrouter/{vnet_id}':
    post:
      summary: Create a new virtual network router
      description: If a virtual network router/vnet with specified vnet_id doesn't exist, new vnet with empty virtual table would be created. If a vnet exists already, it will return error '409', sub-code '0'. If this API is called without a vxlan local vtep created(should be created as a Day 0 config), there will be a failure with code '409' sub-code '1'.
      parameters:
        - name: vnet_id
          in: path
          required: true
          type: string
          description: vnet_id containing the vnet guid as a string
        - name: attr
          in: body
          required: true
          description: attributes for virtual network router
          schema:
            $ref: '#/definitions/VnetEntry'
      responses:
        '204':
          description: OK
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Capacity insufficient
          schema:
            $ref: '#/definitions/Error'
        '409':
          description: Resource Conflict. Virtual network router /VNET already exists OR dependency VxLAN VTEP not found.
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
    get:
      summary: Get information about an existing virtual network router
      description: Returns attributes for requested vnet_id. If the vnet is not defined it returns '404' error.
      parameters:
        - name: vnet_id
          in: path
          required: true
          type: string
          description: vnet_id containing the vnet guid as a string
      responses:
        '200':
          description: OK
          schema:
            type: object
            required:
              - vnet_id
              - attr
            properties:
              vnet_id:
                type: string
                description: vnet_id containing the vnet guid as a string
              attr:
                $ref: '#/definitions/VnetEntry'
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Virtual network router is not found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
    delete:
      summary: Remove a virtual network router
      description: Remove a virtual network router which is defined by vnet_id. If a vnet with 'vnet_id' is not defined the API will return '404'. If the delete is called before all associated VNET routes or Vlans are deleted, it will return error '409' sub-code 2
      parameters:
        - name: vnet_id
          in: path
          required: true
          type: string
          description: vnet_id containing the vnet guid as a string
      responses:
        '204':
          description: OK
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Virtual network router is not found
          schema:
            $ref: '#/definitions/Error'
        '409':
          description: Resource Conflict. Routes exist on Virtual network router/VNET and it may not be deleted prior to deleting all routes.
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
#----------------------------------------------
# VLAN interface 
#----------------------------------------------
    '/config/interface/vlan/{vlan_id}':
    post:
      summary: Create a new vlan interface
      description: Create a new vlan interface with name Vlan{vlan_id} and vlanid set to vlan_id. If such a vlan interface already exists then this method returns the error '409' sub-code 0. If a vnet with specified vnet_id in attr does not exist this function will return error '409' sub-code 1. If the vlan_id passed is less than 2 or greater than 4094 the API will respond with error '400'.
      parameters:
        - name: vlan_id
          in: path
          required: true
          type: integer
          format: int32
          description: 12 bit vlan_id
        - name: attr
          in: body
          required: true
          description: attributes for vlan interface
          schema:
            $ref: '#/definitions/VlanEntry'
      responses:
        '204':
          description: OK
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Capacity insufficient
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Resource not found
          schema:
            $ref: '#/definitions/Error'
        '409':
          description: Resource Conflict. VLAN already exists OR dependency VRF/VNET not found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
    get:
      summary: Get information about an existing vlan interface
      description: Returns attributes for requested vlan. If the vlan interface does not exist on SONiC it returns a '404' error. If the vlan_id passed is less than 2 or greater than 4094 the API will respond with error '400'.
      parameters:
        - name: vlan_id
          in: path
          required: true
          type: integer
          format: int32
          description: 12 bit vlan_id
      responses:
        '200':
          description: OK
          schema:
            type: object
            required:
              - vlan_id
              - attr
            properties:
              vlan_id:
                type: integer
                format: int12
                description: vlan id
              attr:
                $ref: '#/definitions/VlanEntry'
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Vlan interface is not found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
    delete:
      summary: Remove a vlan interface
      description: Remove a vlan interface which is defined by vlan_id. If the vlan interface does not exist on SONiC it returns a '404' error. If the vlan_id passed is less than 2 or greater than 4094 the API will respond with error '400'. If the delete is called before all associated vlan neighbors/members are deleted, this will return error '409' conflict with sub-code 2. 
      parameters:
        - name: vlan_id
          in: path
          required: true
          type: integer
          format: int32
          description: 12 bit vlanid
      responses:
        '204':
          description: OK
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Vlan interface is not found
          schema:
            $ref: '#/definitions/Error'
        '409':
          description:
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
    '/config/interface/vlans':
    get:
      summary: Get information about existing vlan interfaces for given vnet_id
      description: Returns attributes for vlans of requested vnet_id. If the vnet_id does not exist, it returns a '404' error.
      parameters:
        - name: vnet_id
          in: path
          type: string
          required: true
          description: vnet_id containing the vnet guid as a string
      responses:
        '200':
          description: OK
          schema:
            type: object
            required:
              - vnet_id
              - attr
            properties:
              vnet_id:
                type: string
                description: vnet_id containing the vnet guid as a string
              attr:
                type: array
                $ref: '#/definitions/VlansEntry'
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Vnet_id is not found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
    '/config/interface/vlans/all':
    get:
      summary: Get information about all existing vlans configured in the system
      description: Returns attributes for vlans. If no vlans exist, it returns a '404' error.
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              attr:
                type: array
                $ref: '#/definitions/VlansAllEntry'
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Vnet_id is not found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
#----------------------------------------------
# VLAN interface member 
#----------------------------------------------
    '/config/interface/vlan/{vlan_id}/member/{if_name}':
    post:
      summary: Add a physical port to a vlan interface
      description: Add a member to interface Vlan{vlan_id}. If the vlan interface does not exist on SONiC it returns a '404' error. If such a member is already present on this Vlan interface the API returns '409' sub-code 0. If the vlan_id passed is less than 2 or greater than 4094 the API will respond with error '400'. If attr with tagging mode is provided it will be honored in config, if not, the default tagging mode will be set to 'untagged'. Vlan members may be tagged or untagged, but, the Vlan member port may be untagged in only one Vlan interface, deviations from this will cause the API to return '409' sub-code 0. 
      parameters:
        - name: vlan_id
          in: path
          required: true
          type: integer
          format: int32
          description: 12 bit vlan_id
        - name: if_name
          in: path
          required: true
          type: string
          description: Physical port name
        - name: attr
          in: body
          required: true
          description: attribute for vlan member
          schema:
            $ref: '#/definitions/VlanMemberEntry'
      responses:
        '204':
          description: OK
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Capacity insufficient
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Vlan interface is not defined
          schema:
            $ref: '#/definitions/Error'
        '409':
          description: Resource Conflict. VLAN member already exists on this VLAN interface OR Vlan member is being added to 2nd Vlan inteface as an untagged member.
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
    get:
      summary: Get information about an existing vlan port member on an existing vlan interface
      description: Returns attributes for requested vlan member. If the vlan/vlan member is not defined/present on SONiC it returns '404' error. If the vlan_id passed is less than 2 or greater than 4094 the API will respond with error '400'.
      parameters:
        - name: vlan_id
          in: path
          required: true
          type: integer
          format: int32
          description: 12 bit vlan_id
        - name: if_name
          in: path
          required: true
          type: string
          description: Physical port name
      responses:
        '200':
          description: OK
          schema:
            type: object
            required:
               - vlan_id
               - if_name
               - attr
            properties:
               vlan_id:
                 type: integer
                 format: int32
                 description: 12 bit vlan_id
               if_name:
                 type: string
                 description: Physical port name
               attr:
                 $ref: '#/definitions/VlanMemberEntry'
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Vlan interface is not defined/Vlan member is not found on this interface. 
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
    delete:
      summary: Remove a vlan member from a vlan interface
      description: Remove a vlan member from a vlan interface which is defined by vlan_id. If the Vlan interface does not exist on SONiC OR a vlan member 'if_name' is not present on the interface the API will return '404'. If the vlan_id passed is less than 2 or greater than 4094 the API will respond with error '400'.
      parameters:
        - name: vlan_id
          in: path
          required: true
          type: integer
          format: int32
          description: 12 bit vlan_id
        - name: if_name
          in: path
          required: true
          type: string
          description: Physical port name
      responses:
        '204':
          description: OK
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Vlan interface is not defined/Vlan member is not found on this Vlan interface
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
    '/config/interface/vlan/{vlan_id}/members':
    get:
      summary: Get information about all existing vlan port member interfaces for an existing vlan interface
      description: Returns attributes of all the member interfaces for given vlan. If the vlan is not defined/present on SONiC it returns '404' error. If the vlan_id passed is less than 2 or greater than 4094 the API will respond with error '400'.
      parameters:
        - name: vlan_id
          in: path
          required: true
          type: integer
          format: int32
          description: 12 bit vlan_id
      responses:
        '200':
          description: OK
          schema:
            type: object
            required:
               - vlan_id
            properties:
               vlan_id:
                 type: integer
                 format: int32
                 description: 12 bit vlan_id
               attr:
                 type: array
                 $ref: '#/definitions/VlanMembersEntry'
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Vlan interface is not defined.
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
#----------------------------------------------
# VLAN interface neighbor 
#----------------------------------------------
    '/config/interface/vlan/{vlan_id}/neighbor/{ip_addr}':
    post:
      summary: Add the connected end host's IP address to the vlan interface for arp assist and neighbor discovery 
      description: Add the connected end host's IP address to the vlan interface for arp assist and neighbor discovery. If such a neighbor already exists on this Vlan interface then this method returns the error '409' sub-code 0, if the Vlan interface doesn't exist on SONiC this returns error '404'. If the vlan_id passed is less than 2 or greater than 4094 the API will respond with error '400'.
      parameters:
        - name: vlan_id
          in: path
          required: true
          type: integer
          format: int32
          description: 12 bit vlan_id
        - name: ip_addr
          in: path
          required: true
          type: string
          description: Connected end device IP address 
      responses:
        '204':
          description: OK
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Capacity insufficient
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Vlan interface is not found
          schema:
            $ref: '#/definitions/Error'
        '409':
          description: VLAN neighbor already exists on the interface
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
    get:
      summary: Get information about an existing vlan neighbor on an existing vlan interface
      description: Returns HTTP success/failure code for requested neighbor. If the vlan interface/vlan neighbor does not exist on SONiC it returns '404' error. If the vlan_id passed is less than 2 or greater than 4094 the API will respond with error '400'.
      parameters:
        - name: vlan_id
          in: path
          required: true
          type: integer
          format: int32
          description: 12 bit vlan_id
        - name: ip_addr
          in: path
          required: true
          type: string
          description: Connected end device IP address
      responses:
        '200':
          description: OK
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Vlan interface is not found/Vlan neighbor is not found on this interface. 
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
    delete:
      summary: Remove a vlan neighbor from a vlan interface
      description: Remove a vlan neighbor from a vlan interface which is defined by vlan_id. If a vlan interface with 'vlan_id' is not present on SONiC OR a vlan neighbor 'ip_addr' is not present on the interface the API will return '404'. If the vlan_id passed is less than 2 or greater than 4094 the API will respond with error '400'.
      parameters:
        - name: vlan_id
          in: path
          required: true
          type: integer
          format: int32
          description: 12 bit vlan_id
        - name: ip_addr
          in: path
          required: true
          type: string
          description: Connected end device IP address
      responses:
        '204':
          description: OK
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Vlan interface is not found/Vlan neighbor is not found on this Vlan interface
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
    '/config/interface/vlan/{vlan_id}/neighbors':
    get:
      summary: Get information about all vlan neighbors on an existing vlan interface
      description: Returns all the neighbors associated with requested vlan. If the vlan interface does not exist on SONiC it returns '404' error. If the vlan_id passed is less than 2 or greater than 4094 the API will respond with error '400'.
      parameters:
        - name: vlan_id
          in: path
          required: true
          type: integer
          format: int32
          description: 12 bit vlan_id
      responses:
        '200':
          description: OK
          schema:
            type: object
            required:
               - vlan_id
            properties:
               vlan_id:
                 type: integer
                 format: int32
                 description: 12 bit vlan_id
               attr:
                 type: array
                 $ref: '#/definitions/VlanNeighborsEntry'
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Vlan interface is not found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'

#----------------------------------------------
# vxlan tunnel encap object
#----------------------------------------------
  '/config/tunnel/encap/vxlan/{vnid}':
    post:
       description: Return success for now 
       responses:
          '204':
            description: OK
       description: Return success for now
    get:
       responses:
          '204':
            description: OK
    delete:
       description: Return success for now
       responses:
          '204':
            description: OK

#----------------------------------------------
# route object
#----------------------------------------------
  '/config/vrouter/{vnet_id}/routes':
    patch:
      summary: Add/Delete IP routes for a virtual network router. Modifying an existing route is not currently supported
      description: This API call receives a list of route entries to be added/deleted from the virtual routing table defined by 'vnet_id'. If an object with vnet_id doesn't exist this will return an error code '404'. The 'cmd' attribute will determine whether this is an add or delete request. For 'add' operations the API will try to insert every route entry individually. If a route entry doesn't exist in the routing table yet, it will be inserted there. If something went wrong the route entry will be returned as member of "failed" list with "error_code" attr set to some HTTP error code and "error_msg" attr set to some custom error string. Similarly for 'delete' operations the API will try to delete every route entry individually, if the delete fails it will be returned as a member of the "failed" list with attrs "error_code" and "error_msg" set
      parameters:
        - name: vnet_id
          in: path
          type: string
          required: true
          description: vnet_id containing the vnet guid as a string
        - name: attr
          in: body
          required: true
          description: attributes for virtual network router IP prefix
          schema:
            type: array
            items:
              $ref: '#/definitions/RouteEntry'
      responses:
        '204':
          description: OK
        '207':
          description: Multi-Status
          schema:
            type: object
            required:
              - failed
            properties:
              failed:
                description: list of failed routes
                type: array
                items:
                  $ref: '#/definitions/RouteEntry'
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Capacity insufficient
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: VRF/VNET not found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
    delete:
      summary: Remove IP routes for a virtual network router
      description: This API call will remove all route entries from a virtual network router defined by 'vnet_id'. If 'vnid' query parameter is defined, this API call will remove only routes for which nexthop tunnel is 'vnid'. If the removing was unsuccessful it will be added as a member of the "failed" list along with attributes for "error_code" and "error_msg" populated.
      parameters:
        - name: vnet_id
          in: path
          type: string
          required: true
          description: vnet_id containing the vnet guid as a string
        - name: vnid
          in: query
          required: false
          type: integer
          format: int32
          description: vxlan id (24-bit). Allows to remove routes with defined vnid only. Applicable for routes with nexthop_type 'vxlan-tunnel'. Otherwise '400' error will be returned
      responses:
        '204':
          description: OK
        '207':
          description: Multi-Status
          schema:
            type: object
            required:
              - failed
            properties:
              failed:
                description: list of failed routes
                type: array
                items:
                  $ref: '#/definitions/RouteEntry'
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Object not found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
    get:
      summary: Get IP routes for a given virtual network router
      description: Return a list of routing entries for a given virtual network router defined by "vnet_id" parameter. If there're no routing entries an empty list would be returned. The output list could be filterd by "vnid" and "ip_prefix" parameters. If one of the parameters is defined for the request, the output will contain only routing entries which have this parameter in their attributes.
      parameters:
        - name: vnet_id
          in: path
          required: true
          type: string
          description: vnet_id containing the vnet guid as a string
        - name: vnid
          in: query
          required: false
          type: integer
          format: int32
          description: vxlan id (24-bit). Allows to output routes with defined vnid only. Applicable for routes with nexthop_type 'vxlan-tunnel'. Otherwise '400' error will be returned
        - name: ip_prefix
          in: query
          required: false
          type: string
          description: destination IP address block. If presented, get will return information about only this ip prefix
      responses:
        '200':
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/RouteEntry'
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Object not found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
#----------------------------------------------
# tunnel decapsulation endpoint object
#----------------------------------------------
  '/config/tunnel/decap/{tunnel_type}':
    post:
      summary: Setup or update tunnel decapsulation parameters
      description: >-
          For vxlan tunnel, this defines the Virtual Tunnel End point IP address used in all L3 vxlan traffic to/from SONiC. Modifying or deleting is not currently supported.
      parameters:
        - name: tunnel_type
          in: path
          required: true
          type: string
          enum:
            - vxlan
          description: type of a tunnel endpoint
        - name: attr
          in: body
          required: true
          description: attributes for TunnelDecapsulator
          schema:
            $ref: '#/definitions/TunnelDecapEntry'
      responses:
        '204':
          description: OK
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Capacity insufficient
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Object not found
          schema:
            $ref: '#/definitions/Error'
        '409':
          description: Object already exists
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
    get:
      summary: Get tunnel decapsulation parameters
      parameters:
        - name: tunnel_type
          in: path
          required: true
          type: string
          enum:
            - vxlan
          description: type of a tunnel endpoint
      responses:
        '200':
          description: OK
          schema:
            type: object
            required:
              - tunnel_type
              - attr
            properties:
              tunnel_type:
                type: string
                enum:
                  - vxlan
              attr:
                $ref: '#/definitions/TunnelDecapEntry'
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Object not found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
    delete:
      summary: Remove tunnel decapsulation information. For now, this will not delete the object, it will just return success '204' in order to implement as no-op.
      parameters:
        - name: tunnel_type
          in: path
          type: string
          required: true
          enum:
            - vxlan
          description: type of a tunnel endpoint
      responses:
        '204':
          description: OK
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Object not found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
#----------------------------------------------
# VRF config API
#----------------------------------------------
  '/config/vrf/{vrf_id}':
    post:
      summary: Create a new VRF representing a virtual routing instance. If VRF exists, 409 conflict error will be returned
      parameters:
        - name: vrf_id
          in: path
          required: true
          type: string
          description: vrf_id can be a guid
        - name: attr
          in: body
          required: false
          description: optional attributes for VRF
          schema:
            $ref: '#/definitions/VrfEntry'
      responses:
        '204':
          description: OK
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '409':
          description: Resource Conflict
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Capacity insufficient
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
    get:
      summary: Get information about an existing VRF
      description: Returns attributes for requested vrf_id.
      parameters:
        - name: vrf_id
          in: path
          required: true
          type: string
          description: vrf_id representing the virtual routing instance
      responses:
        '200':
          description: OK
          schema:
            type: object
            required:
              - vrf_id
              - attr
            properties:
              vrf_id:
                type: string
              attr:
                $ref: '#/definitions/VrfEntry'
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: VRF is not found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
    delete:
      summary: Remove a VRF
      parameters:
        - name: vrf_id
          in: path
          required: true
          type: string
          description: vrf_id representing the virtual routing instance
      responses:
        '204':
          description: OK
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: VRF is not found
          schema:
            $ref: '#/definitions/Error'
        '409':
          description: Resource Conflict. VRF is associated with other entities (Subinterface/Tunnel)
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
#----------------------------------------------
# Route object for VRF
#----------------------------------------------
  '/config/vrf/{vrf_id}/routes':
    patch:
      summary: Update/modify IP routes for a VRF
      description: This API call receives a list of route entries to be added/modified/deleted from the virtual routing table defined by 'vrf_id'. API shall operate on default vrf if the 'vrf_id' is specified as 'default'. It is not required by the user to create 'default' vrf. For non-default vrf, if an object with vrf_id doesn't exist this will return an error code '404'. The 'cmd' attribute will determine whether this is an add or delete request. For 'add' operations the API will try to insert every route entry individually. If a route entry already exists in the virtual routing table, the attributes of the rouing entry will be updated. If a route entry doesn't exist in the routing table yet, it will be inserted there. If something went wrong the route entry will be returned as member of "failed" list with "error_code" attr set to some HTTP error code and "error_msg" attr set to some custom error string. Similarly for 'delete' operations the API will try to delete every route entry individually, if the delete fails it will be returned as a member of the "failed" list with attrs "error_code" and "error_msg" set
      parameters:
        - name: vrf_id
          in: path
          type: string
          required: true
          description: vrf_id representing the virtual routing instance
        - name: attr
          in: body
          required: true
          description: array of attributes for the routes
          schema:
            type: array
            items:
              $ref: '#/definitions/RouteEntry'
      responses:
        '204':
          description: OK
        '207':
          description: Multi-Status
          schema:
            type: object
            required:
              - failed
            properties:
              failed:
                description: list of failed routes
                type: array
                items:
                  $ref: '#/definitions/RouteEntry'
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Capacity insufficient
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: VRF not found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
    delete:
      summary: Remove IP routes for a virtual routing instance
      description: This API call will remove all route entries from a virtual routing instance defined by 'vrf_id' or 'default' vrf. If 'vnid' query parameter is defined, this API call will remove only routes for which nexthop tunnel is 'vnid'. If the removing was unsuccessful it will be added as a member of the "failed" list along with attributes for "error_code" and "error_msg" populated.
      parameters:
        - name: vrf_id
          in: path
          type: string
          required: true
          description: vrf_id representing the virtual routing instance
        - name: vnid
          in: query
          required: false
          type: integer
          format: int32
          description: vxlan id (24-bit). Allows to remove routes with defined vnid only. Applicable for routes with nexthop_type 'vxlan-tunnel'. Otherwise '400' error will be returned
      responses:
        '204':
          description: OK
        '207':
          description: Multi-Status
          schema:
            type: object
            required:
              - failed
            properties:
              failed:
                description: list of failed routes
                type: array
                items:
                  $ref: '#/definitions/RouteEntry'
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Object not found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
    get:
      summary: Get IP routes for a given virtual routing instance
      description: Return a list of routing entries for a given virtual routing instance defined by "vrf_id" parameter. If there're no routing entries an empty list would be returned. The output list could be filterd by "vnid" and "ip_prefix" parameters. If one of the parameters is defined for the request, the output will contain only routing entries which have this parameter in their attributes.
      parameters:
        - name: vrf_id
          in: path
          required: true
          type: string
          description: vrf_id representing the virtual routing instance
        - name: vnid
          in: query
          required: false
          type: integer
          format: int32
          description: vxlan id (24-bit). Allows to output routes with defined vnid only. Applicable for routes with nexthop_type 'vxlan-tunnel'. Otherwise '400' error will be returned
        - name: ip_prefix
          in: query
          required: false
          type: string
          description: destination IP address block. If presented, get will return information about only this ip prefix
      responses:
        '200':
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/RouteEntry'
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Object not found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
#----------------------------------------------
# QinQ subinterface object
#----------------------------------------------
  '/config/subinterface/qinq/{if_name}/{outer_tag}/{inner_tag}':
    put:
      summary: Create/update QinQ router interface for a physical interface
      description: If the interface is already created, only QinQ attributes can be updated.
      parameters:
        - name: if_name
          in: path
          required: true
          type: string
          description: physical interface name
        - name: outer_tag
          in: path
          type: integer
          format: int32
          required: true
          description: QinQ outer tag
        - name: inner_tag
          in: path
          type: integer
          format: int32
          required: true
          description: QinQ inner tag
        - in: body
          name: attr
          required: true
          description: attributes for QinQ router interface
          schema:
            $ref: '#/definitions/QinQEntry'
      responses:
        '204':
          description: OK
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Capacity insufficient
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Object not found
          schema:
            $ref: '#/definitions/Error'
        '405':
          description: Method not allowed
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
    delete:
      summary: Remove a QinQ router interface from a physical interface
      description: If the router interface doesn't exist, '404' error will be returned.
      parameters:
        - name: if_name
          in: path
          required: true
          type: string
          description: physical interface name
        - name: outer_tag
          in: path
          type: integer
          format: int32
          required: true
          description: QinQ outer tag
        - name: inner_tag
          in: path
          type: integer
          format: int32
          required: true
          description: QinQ inner tag
      responses:
        '204':
          description: OK
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Object not found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
    get:
      summary: Get QinQ router interface information
      description: Return attributes for a given QinQ interface. If there're no interface with such parameters '404' error will be returned.
      parameters:
        - name: if_name
          in: path
          required: true
          type: string
          description: physical interface name
        - name: outer_tag
          in: path
          type: integer
          format: int32
          required: true
          description: QinQ outer tag
        - name: inner_tag
          in: path
          type: integer
          format: int32
          required: true
          description: QinQ inner tag
      responses:
        '200':
          description: OK
          schema:
            type: object
            required:
              - if_name
              - outer_tag
              - inner_tag
              - attr
            properties:
              if_name:
                type: string
                description: physical interface that binds to the QinQ router interface
              outer_tag:
                type: integer
                format: int32
                description: QinQ outer tag
              inner_tag:
                type: integer
                format: int32
                description: QinQ inner tag
              attr:
                $ref: '#/definitions/QinQEntry'
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Object not found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'

  '/config/subinterface/qinq/{if_name}':
    get:
      summary: Get a list of all QinQ router interfaces for a physical interface
      description: If "if_name" is not found on the device, '404' error will be returned. If "if_name" is found, but there're no QinQ router interfaces, an empty list will be returned.
      parameters:
        - name: if_name
          in: path
          required: true
          type: string
          description: physical interface that binds to the QinQ router interfaces
      responses:
        '200':
          description: OK
          schema:
            type: array
            items:
              type: object
              required:
                - outer_tag
                - inner_tag
                - attr
              properties:
                outer_tag:
                  type: integer
                  format: int32
                  description: QinQ outer tag
                inner_tag:
                  type: integer
                  format: int32
                  description: QinQ inner tag
                attr:
                  $ref: '#/definitions/QinQEntry'
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Object not found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'

  '/config/subinterface/qinq/{if_name}/{outer_tag}/{inner_tag}/{shutdown}':
    put:
      summary: Shutdown or startup the subinterface.
      description: If the subinterface doesn't exist, returns '404'
      parameters:
        - in: path
          name: if_name
          type: string
          required: true
          description: physical interface that bound to the QinQ router interface
        - name: outer_tag
          in: path
          type: integer
          format: int32
          required: true
          description: QinQ outer tag of the subinterface
        - name: inner_tag
          in: path
          type: integer
          format: int32
          required: true
          description: QinQ inner tag of the subinterface
        - name: shutdown
          in: path
          required: true
          type: boolean
          description: set to true for shutdown or false for startup
      responses:
        '204':
          description: OK
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Capacity insufficient
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Object not found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'

#----------------------------------------------
# Setup Global BGP process
#----------------------------------------------
  '/config/bgp/{asn}/{router_id}':
    put:
      summary: Setup Global BGP configurations on device
      parameters:
        - name: asn
          in: path
          type: string
          required: true
          description: setup the routing process with this asn
        - name: router_id
          in: path
          type: string
          required: true
          description: ip address to identify the router        
      responses:
        '201':
          description: OK
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Capacity insufficient
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
    delete:
      summary: Remove BGP config
      parameters:
        - name: asn
          in: path
          type: string
          required: true
          description: setup the routing process with this asn
        - name: router_id
          in: path
          type: string
          required: true
          description: ip address to identify the router        
      responses:
        '201':
          description: OK          
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Object not found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
#----------------------------------------------
# Setup BGP neighbors for a VRF
#----------------------------------------------
  '/config/bgp/vrf/{vrf_id}/neighbors/{neighbor_ip}':
    put:
      summary: Setup BGP neighbor on device per VRF. If this neighbor_ip exist, the neighbor attributes will be updated.
      parameters:
        - name: vrf_id
          in: path
          required: true
        - name: neighbor_ip
          in: path
          required: true
        - name: attr
          in: body
          required: true
          description: Attributes for this neighbor
          schema:
            $ref: '#/definitions/NeighborEntry'
      responses:
        '201':
          description: OK          
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Capacity insufficient
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Object not found, if vrouter doesnt exist
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
    delete:
      summary: Remove BGP neighbor for the VRF
      parameters:
        - name: vrf_id
          in: path
          required: true
        - name: neighbor_ip
          in: path
          required: true        
      responses:
       '201':
          description: OK     
          schema:
            $ref: '#/definitions/NeighborEntry'     
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Object not found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
    get:
      summary: Get attributes of this neighbor in the VRF
      parameters:
        - name: vrf_id
          in: path
          required: true
        - name: neighbor_ip
          in: path
          required: true
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/NeighborEntry'
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Object not found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
#----------------------------------------------
# Bgp Neighbor shutdown for neighbors in a VRF
#----------------------------------------------
  '/config/bgp/vrf/{vrf_id}/neighbors/{neighbor_ip}/{shutdown}':
    put:
      summary: Shutdown or startup neighbor within a VRF.
      parameters:
        - name: vrf_id
          in: path
          required: true
          type: string
        - name: neighbor_ip
          in: path
          required: true
          type: string
        - name: shutdown
          in: path
          required: true
          type: boolean
          description: shutdown or bring up
      responses:
        '204':
          description: OK
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Capacity insufficient
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Object not found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'

#----------------------------------------------
# All Bgp Neighbors in a VRF
#----------------------------------------------
  '/config/bgp/vrf/{vrf_id}/neighbors'
    get:
      summary: Get information about all neighbors on in a vrouter
      description: Returns all the neighbors associated with requested vrouter. If the vrf_id does not exist, it returns '404' error.
      parameters:
        - name: vrf_id
          in: path
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/NeighborEntry'
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Vlan interface is not found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'

#----------------------------------------------
# Tunnel encap object for vxlan and gre tunnels
#----------------------------------------------
  '/config/tunnel/encap/{tunnel_type}/{tunnel_name}':
    put:
      summary: Create a tunnel
      description: If a tunnel with this name doesn't exist yet then create a new tunnel with these parameters. If the tunnel already exists, it's attributes will be updated.
      parameters:
        - name: tunnel_type
          in: path
          type: string
          required: true
          enum:
            - vxlan
        - name: tunnel_name
          in: path
          type: string
          required: true
        - name: attr
          in: body
          required: true
          schema:
            $ref: '#/definitions/TunnelEntry'
      responses:
        '204':
          description: OK
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Capacity insufficient
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
    delete:
      summary: Remove a tunnel
      description: If a tunnel with this name exists then remove it. If it doesn't exist return '404' error.
      parameters:
        - name: tunnel_type
          in: path
          type: string
          required: true
          enum:
            - vxlan
        - name: tunnel_name
          in: path
          type: string
          required: true
      responses:
        '204':
          description: OK
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Object not found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
    get:
      summary: Get information about a tunnel
      description: If a tunnel with this name exists then return an objects with the tunnel attributes. Otherwise return '404' error.
      parameters:
        - name: tunnel_type
          in: path
          type: string
          required: true
          enum:
            - vxlan
        - name: tunnel_name
          in: path
          type: string
          required: true
      responses:
        '200':
          description: OK
          schema:
            type: object
            required:
              - attr
            properties:
              attr:
                $ref: '#/definitions/TunnelEntry'
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Object not found
          schema:
            $ref: '#/definitions/Error'
        '500':
         description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
                
#----------------------------------------------
# All configured tunnels
#----------------------------------------------
  '/config/tunnel/encap/{tunnel_type}':
    get:
      summary: Get a list of existing tunnels of a tunnel_type
      description: Return a list of existing tunnels of a type. If there're no tunnels to return, empty list will be returned.
      parameters:
        - name: tunnel_type
          in: path
          type: string
          required: true
          enum:
            - vxlan
      responses:
        '200':
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/TunnelEntry'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'            
#----------------------------------------------
# Shutdown or startup a tunnel
#----------------------------------------------
  '/config/tunnel/encap/{tunnel_type}/{tunnel_name}/{shutdown}':
    put:
      summary: Shutdown or startup a tunnel
      parameters:
        - name: tunnel_type
          in: path
          type: string
          required: true
          enum:
            - vxlan
        - name: tunnel_name
          in: path
          type: string
          required: true
        - name: shutdown
          in: path
          required: true
          type: boolean
      responses:
        '204':
          description: OK
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Capacity insufficient
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
#----------------------------------------------
# Setup BFD session
#----------------------------------------------
  '/config/bfd/{bfd_session}':
    put:
      summary: Setup BFD session
      description: If a BFD session with this name exists, updates are only allowed on "shutdown" status. For any other change, return '500' error
      parameters:
        - name: bfd_session
          in: path
          type: string
          maxLength: 32
          required: true
          description: uniquely identifiable string (32 characters) to represent a BFD session. This will be referred to while setting up the Neighbor for a certain interface to receive BFD notification
        - name: attr
          in: body
          required: true
          schema:
            $ref: '#/definitions/BfdEntry'
      responses:
        '204':
          description: OK
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Capacity insufficient
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
    delete:
      summary: Remove the bfd session
      description: If the session is running (not shutdown), return '500' error with message asking for shutdown first before attempting to remove. If this session doesn't exist return '404' error.
      parameters:
        - name: bfd_session
          in: path
          type: string
          maxLength: 32
          required: true
          description: uniquely identifiable string (32 characters) to represent a BFD session.
      responses:
        '204':
          description: OK
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Object not found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
    get:
      summary: Get information about a bfd_session
      description: If a bfd session with this name exists then return an objects with the bfd attributes. Otherwise return '404' error.
      parameters:
        - name: bfd_session
          in: path
          type: string
          maxLength: 32
          required: true
          description: uniquely identifiable string (32 characters) to represent a BFD session.
      responses:
        '200':
          description: OK
          schema:
            type: object
            required:
              - attr
            properties:
              attr:
                $ref: '#/definitions/BfdEntry'
        '400':
          description: Malformed arguments for API call
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Invalid authentication credentials
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Object not found
          schema:
            $ref: '#/definitions/Error'
        '500':
         description: Internal service error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Maintanence mode
          schema:
            $ref: '#/definitions/Error'
#----------------------------------------------
# Schema definitions
#----------------------------------------------
definitions:
  Error:
    type: object
    properties:
      error:
        type: object
        required:
          - code
          - message
        properties:
          code:
            type: integer
            format: int32
          sub-code:
            type: integer
            format: int32
          message:
            type: string
          fields:
            type: array
            items:
              type: string
          details:
            type: string
  RouteEntry:
    type: object
    required:
      - ip_prefix
      - nexthop
    properties:
      cmd:
        description: >-
          add/delete, this defines the operation to perform on the route for the PATCH function.
          note, this is REQUIRED for PATCH and will not be populated for GET/DELETE 
      ip_prefix:
        description: >-
          destination IP address block, either customer advertised
          on-premise IP prefix block or customer VM IP address.
        type: string
      nexthop_type:
        type: string
        enum:
          - ip
          - vxlan-tunnel
        description: next hop type. ip nexthop or vxlan tunnel nexthop. For future, we can more tunnel nexthop such as vxlan-gpe,nvgre, etc. on
      nexthop:
        type: string
        description: >-
          ip address of nexthop. 'comma' seperated list for ecmp (equal cost multipath) routes; User can optionally specify emtpy '' strings for positional arguments.
          When nexthop_type is 'ip', then nexthop is the CE IP address;
          When nexthop_type is 'vxlan_tunnel', the next hop is the PA address of the customer VM
      mac_address:
        type: string
        description: mac_address of the target VM
      ifname:
        type: string
        description: Interface name for local route. When ifname is mentioned, nexthop is optional. 'comma' seperated list for ecmp routes; User can optionally specify empty '' strings for positional arguments.
      vnid:
        type: integer
        format: int32
        description: vxlan id to be used for the tunnel. Optional arg. If it isn't provided the default vxlan id defined for the vnet/vrf will be used as the destination vnid.
      error_code:
        type: integer
        format: int32
        description: HTTP error code for the failing route
      error_msg:
        type: string
        description: error message for the failing route
  TunnelDecapEntry:
    type: object
    required:
      - ip_addr
    properties:
      ip_addr:
        type: string
        description: tunnel local termination IP address
  VnetEntry:
    type: object
    required:
      - vnid
    properties:
      vnid:
        type: integer
        format: int32
        description: vnid
  VlanEntry:
    type: object
    properties:
      vnet_id:
        type: string
        description: vnet_id containing the vnet guid as a string
      ip_prefix:
        description: >-
          Vlan interface IP address and prefix, this will act as
          the default gateway to/from the HSM. 
        type: string
  VlansEntry:
    type: object
    properties:
      vlan_id:
        type: integer
        format: int32
        description: 12 bit vlan_id
      ip_prefix:
        description: >-
          Vlan interface IP address and prefix, this will act as
          the default gateway to/from the HSM.
        type: string
  VlansAllEntry:
    type: object
    properties:
      vlan_id:
        type: integer
        format: int32
        description: 12 bit vlan_id
      vnet_id:
        type: string
        description: vnet_id containing the vnet guid as a string
      ip_prefix:
        description: >-
          Vlan interface IP address and prefix
        type: string
  VlanMemberEntry:
    type: object
    properties:
      tagging_mode:
        type: string
        description: "tagged/untagged describes the vlan member's tagging mode, eg: HSM accepts only untagged traffic"
  VlanMembersEntry:
    type: object
    properties:
      tagging_mode:
        type: string
        description: "tagged/untagged describes the vlan member's tagging mode, eg: HSM accepts only untagged traffic"
      if_name:
        type: string
        description: Physical port name
  VlanNeighborsEntry:
    type: object
    properties:
      ip_addr:
        type: string
        description: IP address of directly attached device to the switch
  BfdEntry:
    type: object
    properties:
      if_name:
        type: string
        description: source of the BFD
      tx_interval:
        type: integer
        description: interval in milliseconds that this system will use between transmission of control packets
        default: 300
      rx_interval:
        type: integer
        descrition: minimum in milliseconds interval this system is capable of receiving control packets
        default: 300
      multiplier:
        type: integer
        description: detection multiplier to detect packet loss for incoming packets
        minimum: 1
        maximum: 255
        default: 3
      echo_interval:
        type: integer
        description: minimum interval in milliseconds for transmission of echo packets
        default: 300
      echo_mode:
        type: boolean
        description: enables or disables echo packets
        default: false
      passive_mode:
        type: boolean
        description: does not start the connection and wait for control packets to start replying to
        default: false
      minimum_ttl:
        type: integer
        description: used when the peers are multihop. Default value of 255 indicate only one hop between peers
        minimum: 1
        maximum: 255
        default: 255
      shutdown:
        type: boolean
        description: set to false to enable
  QinQEntry:
    type: object
    properties:
      description:
        type: string
      vrf_id:
        type: string
        description: id representing the virtual routing instance (VRF) this Subinterface is associated to.
      ip_addr:
        type: string
        description: subinterface ipv4 address
      mask:
        type: string
        description: subinterface ipv4 mask
  NeighborEntry:
    type: object
    properties:
      neighbor_ip:
        type: string
      neighbor_as:
        type: integer
      bfd_session:
        type: 'string'
        description: a previously setup bfd_session name. This is an optional parameter. If the bfd_session name is not provided, bfd is disabled for this neighbor.
      max_routes:
        $ref: '#/definitions/MaxRoutesEntry'
  TunnelEntry:
    type: object
    properties:
      tunnel_name:
        type: string
      description:
        type: string
      src_ip:
        type: string
        format: ipv4
      vrf_id:
        type: string
        description: id representing the virtual routing instance (VRF) this tunnel is associated to.
      encap_src:
        type: string
      encap_dst:
        type: string
      vni:
        type: integer
        format: int32
        description: vxlan id (24-bit)
  VrfEntry:
    type: object
    properties:
      ipv4_max_routes:
        $ref: '#/definitions/MaxRoutesEntry'
  MaxRoutesEntry:
    type: object
    properties:
      num:
        description: maximum routes allowed for this entity (vrf/neighbor)
        type: integer
      threshold:
        description: after what threshold should a warning be generated (1-100)
        type: integer