Sherpa API Information
The Sherpa client is based upon 10 cosign protected web services. These services take inputs as standard CGI parameters and return JSON formatted output. Almost all services require the net and wg parameters to define the security context.
VLAN editing is currently implemented by removing a VLAN and then re-adding it, which is to say edits are disruptive to packet forwarding.
Generally the planning services are used to figure out the design of the vlan, then the provisioning services are user to either add or remove a vlan.
Planning Services:
This section contains 8 services used to plan out the provisioning request.
getActivationHistory.cgi
Provides a history of Sherpa provisioning for circuits within the provided administrative network and workgroup. Additionally, supports a search pattern to restrict history output to a keyword search that is applied to the circuit’s name, description and vlan tag.
Required CGI Parameters:
- net
- admin network identifier, always 1 for NLR for instance
- wg
- work group id to operate under, getWorkgroups.cgi used to resolve this
Optional CGI Parameters:
- search
getAvailableTag.cgi
Provides the next available unused VLAN tag. If optional tag is provided then will let you know if that tag is available or the nearst greater value.
Required CGI Parameters:
- net
Optional CGI parameters:
- tag
- desired vlan tag number.
getEntities.cgi
Provides a list of organizational entities. Each VLAN needs to be associated with an Entity.
Required CGI Parameters:
- net
- wg
getExistingVlans.cgi
Provides list of VLANs that belong to a given work group.
Required CGI Parameters:
- net
- wg
Optional CGI Parameters:
- search
getInterfaces.cgi
Returns a list of interfaces on the specified node that the specified workgroup is allowed to use as VLAN endpoints.
Required CGI Parameters:
- net
- wg
- short_name
- FQDN for the router/switch of interest.
Optional CGI Parameters:
- search
getTrunks.cgi
Provides a list of trunks upon which the specified VLAN is currently provisioned over.
Required CGI Parameters:
- net
- ck_id
- this VLANs circuit ID
getVlanHistory.cgi
Provides the provisioning history for a given VLAN. Accepts either VLAN Tag or ckg_id.
Required CGI Parameters:
- net
- wg
- tag or ckt_id
getVlanSPF.cgi
Based on 2 defined endpoints, this service will provide the shortest available path considering available bandwidth.
Required CGI Parameters:
- net
- reserved_bw
- bytes per second integer to represent amount of bandwidth to reserve.
- node_a
- FQDN hostname for the first node/endpoint
- node_z
- FQDN hostname for the second node/endpoint
getWorkgroups.cgi
Provides the list of Sherpa workgroups that the user is allowed to access.
Required CGI Parameters:
- net
isTagAvailable.cgi
Checks to see if a defined VLAN tag is available.
Required CGI Parameters:
- net
- tag
Provisioning Services:
provisionVlan.cgi
This service is used to provision a VLAN on the network. Typically all data used to build this request is gathered via the planning aids.
Required CGI Parameters:
- net
- wg
- tag
- VLAN Tag
- reserved_bw
- reserved bandwidth in bytes per second
- description
- human friendly description
- node_a
- the host name for endpoint a device
- node_z
- the host name for the endpoint z device
- int_a
- the endpoint a interface
- int_z
- the endpoint z interface
- node_rb
- node name for switch to act as Spanning Tree Root Bridge
- path
- comma delimited list of trunks to activate the VLAN upon
- entity_id
- entity id for the assocated entity
removeVlan.cgi
Service used to remove a vlan from the network.
Required CGI Parameters:
- net
- wg
- ckt_id
Optional CGI Parameters:
- no_writemem
- this tells all the switches to not save the config, if you are editing a vlan, setting this on the removal will save 10 seconds of down time, because we will only save the config after we do the final edit.
