API implementation notes

gistfile1.txt

  Device
  GET /device?q={search}&{params} # Lists ALL devices OR filters by search and/or params, if present
  # params: vendor, dns, name, location, ip, description
  # these can hopefully be autogenerated/parsed
  # Example Output:
  #[
  #  {
  #    "device": "some-device.some.net",
  #    "location": "some-location",
  #    "system_name": "some-device",
  #    "modem": "EX2300-C-12T",
  #    "management_ip": "10.20.30.40",
  #    "url": "https://netdisco.some.net/api/device/10.20.30.40"
  #  },
  #  {
  #    "device": "some-other-device.some.net",
  #    "location": "some-location",
  #    "system_name": "some-other-device",
  #    "modem": "EX2300-24P",
  #    "management_ip": "10.20.30.45",
  #    "url": "https://netdisco.some.net/api/device/10.20.30.45"
  #  }
  #]
  POST /device # Creates a device.
  # Request Body:
  #{
  #  "device": "{ip/hostname}",
  #  "location": "{some-location}",
  #  "contact":  "{contact}"
  #}
  # Success Response:
  # 201, Body:
  #{
  #  "url": "https://netdisco.some.net/api/device/{ip/hostname}"
  #}
  GET /device/{ip} # Gets Device Generic Info
  GET /device/{ip}/{query} 
  #  query is one of:
  #  Details
  #  Ports
  #  Modules
  #  Neighbors
  #  Addresses
  #  VLANs

  PATCH /device/{ip} # Can update location and contact info I guess?
  DELETE /device/{ip} # Deletes device

# Should just be data access, so no POST/PATCH/PUT/DELETE/etc needed
Node:
  GET /node?q={search}?{params} 
  # params: ip, mac, vendor, date range, etc.
  GET /node/{mac} # technically ':' is reserved in urls, needs encoding
  GET /node/{mac}/{queries} # not sure if any are needed

VLANs: (root or under reports?)
  GET /vlan?q={search}&{params}
  # params: id, name
  GET /vlan/{vl_name} # name is primary key?


# Should just be data access, so no POST/PATCH/PUT/DELETE/etc needed
Report:
  # implement in App::Netdisco::Web::Plugin ?
 
PortControl
 
  GET /ports?q={search}&{params} # port search should probably be here
  # params: name, vlan, speed, status, etc
  #Example output:
  #[
  #  {
  #    "status": "up",
  #    "name": "ge-0/0/0",
  #    "description": "I am very much a real port",
  #    "device": "10.20.30.40",
  #    "pvid": 30,
  #    "url": "https://netdisco.some.net/api/port/10.20.30.40/port/ge-0/0/0"
  #  },
  #  {
  #    "status": "up",
  #    "name": "ge-0/0/0",
  #    "description": "100 percent a real port. Yes.",
  #    "device": "10.20.30.45",
  #    "pvid": 4090,
  #    "url": "https://netdisco.some.net/api/port/10.20.30.45/port/ge-0/0/0"
  #  }
  #]
  
  
  # If my understanding of the db is correct, ports should unique per a {device} and {port} identifier
  # Maybe a path of /device/{ip}/port/{port} (use snmp id or ifDescr/etc?) ?
  # Could also add uuid or some kind of token to decode into {device} and {port}?
  # implement in the PortControl.pm module
  
  location
  contact
  portcontrol
  portname
  vlan
  power

AdminTask
  # implement in the AdminTask.pm module
  # anything which is a Worker Action
  # use standard params (device, extra)
  
  GET    /admin/jobs?q={search}&{params}
  # whatever params are needed (if any)
  POST   /admin/jobs # start new job, pass job type in json. Returns job id (does this exist?)
  # data to launch discover of device "10.20.30.40". 
  #{
  #  "job_type": "discover",
  #  "job_details": {           # To allow more flexibility than simply devices maybe?
  #    "device": "10.20.30.40"
  #  }
  #}
  GET    /admin/jobs/{job_id} #Get job status and info 
  
  
  #Below just copied from main netdisco
  GET    /admin/slowdevices       # slow devices
  GET    /admin/performance       # performance
  GET    /admin/timedoutdevices   # snmp failured
  GET    /admin/duplicatedevices  # duplicates
  GET    /admin/orphaned          # orphaned
  GET    /admin/userlog           # get user activity log
  
  GET    /admin/topology # list manual topo
  POST   /admin/topology # add topo entry, returns id (if exists?)
  GET    /admin/topology/{id} 
  PATCH  /admin/topology/{id} 
  DELETE /admin/topology/{id} 


  GET    /admin/pseudodevice      # list pseudodev
  POST   /admin/pseudodevice      # add pseudodev, returns id (if exists?)
  GET    /admin/pseudodevice/{id} 
  PATCH  /admin/pseudodevice/{id} 
  DELETE /admin/pseudodevice/{id} 

  GET    /admin/user # Gets list of all users
  POST   /admin/user # Create new user
  GET    /admin/user/{user} # user info
  PATCH  /admin/user/{user} # update user
  DELETE /admin/user/{user} # delete user