Ridgeline 4.0 REST API Quick Start PDF - Extreme Networks

Ridgeline 4.0 REST API QuickStart

Copyright ©© 2013 Extreme Networks, Inc. All Rights Reserved.Extreme Networks and the Extreme Networks logo are trademarks or registered trademarks ofExtreme Networks, Inc. in the United States and/or other countries.AccessAdapt, Alpine, Altitude, BlackDiamond, EPICenter, Essentials, Ethernet Everywhere,Extreme Enabled, Extreme Ethernet Everywhere, Extreme Networks, Extreme Standby RouterProtocol, Extreme Turbodrive, Extreme Velocity, ExtremeWare, ExtremeWorks, ExtremeXOS, GoPurple Extreme Solution, Ridgeline, ScreenPlay, Sentriant, ServiceWatch, Summit, SummitStack,Triumph, Unified Access Architecture, Unified Access RF Manager, UniStack, the ExtremeNetworks logo, the Alpine logo, the BlackDiamond logo, the Extreme Turbodrive logo, the Summitlogos, and the Powered by ExtremeXOS logo are trademarks or registered trademarks of ExtremeNetworks, Inc. or its subsidiaries in the United States and/or other countries.Active Directory is a registered trademark of Microsoft.sFlow is a registered trademark of InMon Corporation.XenServer is a trademark of Citrix.vCenter is trademark of VMware.Specifications are subject to change without notice.All other names are the property of their respective owners.For additional information on Extreme Networks trademarks, please see:www.extremenetworks.com/about-extreme/trademarks.aspx.

Table of ContentsChapter 1: Introduction 4Overview 4Audience 4What Is REST? 4Advantages of REST over SOAP 4Limitations 5Chapter 2: What is Supported in REST? 6REST Support for Ridgeline 4.0 Devices 6REST Support for Ridgeline 4.0 Slots 7REST Support for Ridgeline 4.0 Ports 8REST Support for Ridgeline 4.0 Topology 8REST Support for Ridgeline 4.0 ExtremeXOS Network Virtualization 10REST Support for Ridgeline 4.0 Identity Management 11Pagination Support 14Filtering Support 14Chapter 3: Authentication and Exceptions 15Authentication 15Exceptions 15Exception Information 16Chapter 4: Using the REST API 18Using the REST API through a Browser 18Using REST API through a Simple Java Program 19Java Program 19Code Example 21Ridgeline 4.0 REST API Quick Start 3

1 IntroductionOverviewAudienceWhat Is REST?Advantages of REST over SOAPLimitationsOverviewThis quick start is intended as a reference for the REST API, which allows a client application to query anetwork management server running Ridgeline 4.0 or later. Extreme Networks REST XML API enablesreliable external device-to-device management communication. The API interface provides amechanism to communicate with Extreme Networks network management servers using XMLmessages. Its standards-based REST/XML architecture makes it easy to integrate the networkinfrastructure with higher-level application and business software. In this release, the interface may beused to retrieve the network inventory (devices, slots, ports, and links).AudienceThis guide is intended for software developers using a programming interface to write applications forExtreme Networks devices. It assumes a basic working knowledge of the following:• Concepts and operation of XML API interfaces and web services• Writing web services client code in JavaWhat Is REST?REST (Representational State Transfer) is a set of constraints that when applied to the design of asystem creates a software architectural style that exploits the existing technology and protocols of theweb, including HTTP (Hypertext Transfer Protocol) and XML (Extensible Markup Language).Advantages of REST over SOAPRidgeline 4.0 uses a new API REST instead of SOAP (Simple Object Access Protocol), which was theAPI of previous releases. REST has the following advantages over SOAP:• REST facilitates the transaction between web servers by allowing loose coupling between differentservices.• REST is less strongly typed than SOAP.

Introduction• Unlike SOAP, REST does not require XML parsing and does not require a message header to andfrom a service provider, thus using less bandwidth.LimitationsThe following limitations apply to REST support in Ridgeline 4.0:• Only HTTP GET operations are supported.• HTTPS is not supported by the Ridgeline 4.0 web server.• Field selection of entities is not supported.• Embedded Boolean statements within query strings are not supported.• Caching is not supported.Ridgeline 4.0 REST API Quick Start 5

2 What is Supported in REST?REST Support for Ridgeline 4.0 DevicesREST Support for Ridgeline 4.0 SlotsREST Support for Ridgeline 4.0 PortsREST Support for Ridgeline 4.0 TopologyREST Support for Ridgeline 4.0 ExtremeXOS Network VirtualizationREST Support for Ridgeline 4.0 Identity ManagementPagination SupportFiltering SupportREST Support for Ridgeline 4.0 DevicesThe following table shows the URIs to fetch (GET) specific device attributes and device collectioninformation. The next table lists the supported device attributes along with any supported filters(usable as query string).NoteIf desired, you can filter a GET operation to return data that matches your designated criteriausing a query string (also referred as a filter). For more information about using query strings,see Filtering Support on page 14.Table 1: REST Support for Ridgeline 4.0 DevicesResourceDeviceDevice collectionURIhttp://:/v1.0/ dataservice/inventory/device[.xml/.json]Example: http://localhost:8080/v1.0/ dataservice/inventory/device.xmlhttp:///:/v1.0/ dataservice/inventory/device/ [.xml/.json]Example: http://10.120.90.12:8080/v1.0/ dataservice/inventory/device/1.jsonTable 2: REST Supported Attributes for DevicesAttribute Meaning Usable as Query StringNameUser-assigned device nameIP IPv4 address YesIPv6IPv6 addressMACSystem MAC addressSoftwareSoftware versionNetworkStatus Reachable/not reachableAlarmState Critical, major, minor, none Yes

What is Supported in REST?Table 2: REST Supported Attributes for Devices (continued)Attribute Meaning Usable as Query StringHWModelIDHardware modelInternal ID of the deviceNoteWhen you perform a GET on a device collection, the IDs retrieved can then beused to retrieve individual devices using a specific device GET operation.SerialNumberSerial number of deviceREST Support for Ridgeline 4.0 SlotsThe following table shows the URIs to fetch (GET) specific slot attributes and slot collectioninformation. The next table lists the supported slot attributes along with any supported filters (usableas query string).NoteIf desired, you can filter a GET operation to return data that matches your designated criteriausing a query string (also referred as a filter). For more information about using query strings,see Filtering Support on page 14.Table 3: REST Support for Ridgeline 4.0 SlotsResourceSlotSlot collectionURIhttp:///:/v1.0/dataservice/ inventory/slot[.xml/.json]Example: http://10.120.90.12:8080/v1.0/ dataservice/inventory/slothttp:///:/v1.0/dataservice/ inventory/slot/{id}[.xml/.json]Example: http://10.120.90.12:8080/v1.0/ dataservice/inventory/slot/1Table 4: REST Supported Attributes for SlotsAttribute Meaning Usable as Query StringIDSerialNumberMACHWModelHWModelConfiguredPositionSystem-assigned IDMAC addressNoteWhen you perform a GET on a slot collection, the IDs retrieved can thenbe used to retrieve individual slots using a specific slot GET operation.Hardware model presentConfigured hardware modelSlot number or stack positionParentID ID of containing system YesRidgeline 4.0 REST API Quick Start 7

What is Supported in REST?The following table shows the URIs to fetch (GET) specific topology attributes and topology collectioninformation. The next table lists the supported topology attributes along with any supported filters(usable as query string).NoteIf desired, you can filter a GET operation to return data that matches your designated criteriausing a query string (also referred as a filter). For more information about using query strings,see Filtering Support on page 14.Table 7: REST Support for Ridgeline 4.0 TopologyResource URI FiltersMap linkMap link collectionDevice links with MACDevice links with IPhttp:///:/v1.0/dataservice/topology/link/http:///:/v1.0/dataservice/topology/link/http:///:/v1.0/dataservice/dataservice/toplology/link?MAC=00:04:96:27:81:aehttp:///:/v1.0/dataservice/dataservice/toplology/link?IP=10.127.3.63MACIPLinkSateLinkTypeDiscoveryProtocolTable 8: REST Supported Attributes for TopologyAttribute Meaning Usable as Query StringIDUnique IDNoteWhen you perform a GET on a topology collection, the IDs retrieved canthen be used to retrieve individual topology entities using a specifictopology GET operation.Discoverprotocol Discovery protocol of the link YesEndPointAIdEndPointBIdEndPointAPortEndPointBPortEndPointAMacEndPointBMacEndPointAAnnotationEndPointBAnnotationID of A end of linkID of B end of linkPort of A end of linkPort of B end of linkMAC address of A end of linkMAC address of B end of linkAnnotation of A end of linkAnnotation of B end of linkLinkState State of the link YesLinkType Type of the link YesRidgeline 4.0 REST API Quick Start 9

What is Supported in REST?REST Support for Ridgeline 4.0 ExtremeXOS NetworkVirtualizationThe following table shows the URIs to fetch (GET) specific XNV attributes and XNV collectioninformation. The subsequent tables list the supported XNV attributes along with any supported filters(usable as query string).NoteIf desired, you can filter a GET operation to return data that matches your designated criteriausing a query string (also referred as a filter). For more information about using query strings,see Filtering Support on page 14.Table 9: REST Support for Ridgeline 4.0 XNVResourceURIVPPhttp:///:/v1.0/dataservice/xnv/vpp/VPP collectionhttp:///:/v1.0/dataservice/xnv/vppPolicyhttp:///:/v1.0/dataservice/xnv/policy/Policy collectionhttp:///:/v1.0/dataservice/xnv/policyVMhttp:///:/v1.0/dataservice/xnv/vm/VM collectionhttp:///:/v1.0/dataservice/xnv/vmTable 10: REST Supported Attributes for VPPsAttribute Meaning Usable as Query StringNameIDAdministratively assigned nameUnique identifier of VPPNoteWhen you perform a GET on a XNV collection, the IDs retrieved can then beused to retrieve individual XNV entities using a specific XNV GET operation.DescriptionIngressPolicyEgressPolicyAdministratively assigned descriptionIngress policy and priorityEgress policy and priorityTable 11: REST Supported Attributes for PoliciesAttribute Meaning Usable as Query StringNameIDDescriptionRule (see the following table)Administratively assigned nameUnique identifier of policyAdministratively assigneddescriptionName of ACL rule n (1 of more)Ridgeline 4.0 REST API Quick Start 10

What is Supported in REST?Table 12: REST Supported Attributes for RulesAttribute Meaning Usable as Query StringNameMatchActionModifierAdministratively assigned ruleMatch conditionDrop or forwardModifiers (byte-count,meter, etc.)Table 13: REST Supported Attributes for VMsAttribute Meaning Usable as Query StringNameName of the VM obtained from VMMIDSystem-assigned identifierMAC MAC address of the VNIC YesIP Address IPv4 address of the VNIC YesVPPVPP-assigned to this VMPowerStatus On, off, or suspended YesDeviceIP IP address of detecting device YesDevicePortPort number of detecting deviceHostIPAddress of hostHostNameName of hostDataCenterName of data centerREST Support for Ridgeline 4.0 Identity ManagementThe following table shows the URIs to fetch (GET) specific IDM attributes and IDM collectioninformation. The subsequent tables list the supported IDM attributes along with any supported filters(usable as query string).NoteIf desired, you can filter a GET operation to return data that matches your designated criteriausing a query string (also referred as a filter). For more information about using query strings,see Filtering Support on page 14.Table 14: REST Support for Ridgeline 4.0 IDMResourceURIPolicyhttp:///:/v1.0/dataservice/idm/policy/Policy collectionhttp:///:/v1.0/dataservice/idm/policyIDM-enabled devicehttp:///:/v1.0/dataservice/idm/device/Ridgeline 4.0 REST API Quick Start 11

What is Supported in REST?Table 14: REST Support for Ridgeline 4.0 IDM (continued)ResourceURIIDM-enabled device collection http:///:/v1.0/dataservice/idm/deviceIDM porthttp:///:/v1.0/dataservice/idm/port/IDM port collectionhttp:///:/v1.0/dataservice/idm/portIdentityhttp:///:/v1.0/dataservice/idm/identity/Identities collectionhttp:///:/v1.0/dataservice/idm/identityRolehttp:///:/v1.0/dataservice/idm/roles/Role collectionhttp:///:/v1.0/dataservice/idm/rolesTable 15: REST Supported Attributes for RolesAttribute Meaning Usable as Query StringNameIDAdministratively assigned nameSystem-assigned identifierNoteWhen you perform a GET on a IDM collection, the IDs retrieved can then beused to retrieve individual IDM entities using a specific IDM GET operation.PriorityStatusDescriptionParentChild-roleMatch criteriaNumeric priority (0–255) low to highAttached or not attachedHuman-readable descriptionParent role name or noneName of child roleMatch criteriaTable 16: REST Supported Attributes for PoliciesAttribute Meaning Usable as Query StringNameIDDescriptionRule (see the following table)Administratively assigned nameUnique identifier of policyAdministratively assigneddescriptionName of ACL rule n (1 or more)Table 17: REST Supported Attributes for RulesAttribute Meaning Usable as Query StringNameAdministratively assigned ruleMatchMatch conditionRidgeline 4.0 REST API Quick Start 12

What is Supported in REST?Table 17: REST Supported Attributes for Rules (continued)Attribute Meaning Usable as Query StringActionModifierDrop or forwardModifiers (byte-count,meter, etc.)Table 18: REST Supported Attributes for IdentitiesAttribute Meaning Usable as Query StringNameIDRoleLogonMACDeviceIPIdentityIPAuthMethodIdentityTypePortUser ID, system-assigned name, orMAC addressSystem-assigned identifierRole assigned by IDM subsystem ofedge deviceDate/time user was identifiedMAC addressEdge device IP addressIP address of detected entityMethod of authentication:Kerboeros, RADIUS, etc.Machine, humanPort identifier on edge deviceTable 19: REST Supported Attributes for DevicesAttribute Meaning Usable as Query StringDeviceIPIDIDM-EnabledRBM-EnabledPortDirectoryServerBaseDNUserNamePasswordACL-SourceTypeKerberosAgingTimeKerberosForceAgingIP address of device with IDMenabledSystem-assigned identifierTrue or falseTrue or falsePort configurationMAC or IP10..1024 (minutes)0..180 (minutes)Ridgeline 4.0 REST API Quick Start 13

What is Supported in REST?Table 20: REST Supported Attributes for PortsAttribute Meaning Usable as Query StringDeviceIPIP address of device containing portIDSystem-assigned identifierPortRange Port range specifications (1–32)IDM-EnabledTrue or falseRBM-EnabledTrue or falsePagination SupportClients can request the numbers and starting point of the entities to a GET response using these twoparameters:• Offset—indicates the beginning index• Limit—indicates the total number of entities that the client can acceptExamples:HTTP GET ridgeline.co.com:8081/v1.0/dataservice/inventory/devices?limit=50(Retrieves the first 50 entries. Note that offset=1 is implied.)HTTP GET ridgeline.co.com:8081/v1.0/dataservice/inventory/devices?offset=50&limit=50(Retrieves the next 50 entries.)Filtering SupportFiltering allows you to separate desired data that matches your designated criteria from a larger dataset. URL GET retrievals can be filtered using query-string style filters that meet these conditions:• Query strings can be combined together with an implied “AND”.• A specific query string can appear only once in the URL.The query string filtering format is: ?filter=valueExample:A client can retrieve a list of devices that are down (or unreachable) using this URL:HTTP GET ridgeline.co.com:8081/v1.0/dataservice/inventory/devices?status=downRidgeline 4.0 REST API Quick Start 14

3 Authentication and ExceptionsAuthenticationExceptionsException InformationAuthenticationClients must provide credentials to access the API; no anonymous access is allowed. The REST API usesthe authentication methods built-in to HTTP. Security credentials are validated by the existingmechanism for Ridgeline users, permitting access for both locally defined users as well as thoseauthenticated via RADIUS authorization. There is no dedicated REST request to deliver the user’scredentials to the server; the credentials are provided using basic auth-method.ExceptionsThe API service supports the following HTTP status codes.Table 21: Supported HTTP Status CodesHTTP Status CodesDescription200 OK The request was executed successfully (or suppress_errors=true).400 Bad Request The request is invalid.This error code appears for a variety of reasons:• The request format is invalid, specifying unsupported querystrings or invalid entity fields.• The request is incomplete—missing required fields for an entitycreation.• The request cannot be completed due to the exhaustion of aninternal resource.• The request violates an internal limit (the maximum number ofentities that can be returned in a retrieval request or themaximum number of entities that can be updated in a singleoperation).401 Unauthorized The supplied authentication credentials are invalid for the request.This error code appears for two reasons:• The credentials are not present within the request.• The credentials are invalid.

Authentication and ExceptionsTable 21: Supported HTTP Status Codes (continued)HTTP Status CodesDescription403 Forbidden The request is valid, but cannot be executed at this time.The server understands the request, and the request is valid, but theserver refuses to process it for one of the following reasons:• The credentials represent a user who is not allowed to performthe requested operation (a read-only user, for example, may nothave permission to create a new entity).• A modification, creation, or deletion operation was attemptedagainst a read-only entity.404 Not Found The request references an unknown URL.406 Not Acceptable Exception When a client makes a request of a server, it indicates the type ofdata it can accept. If a server is capable only of producing data thatthe client will find unacceptable, it instead returns this exception.408 Request Timeout An internal service did not respond in a timely manner.500 Internal Error The API encountered an unexpected error (a database connectionfailed, a service timed out, etc.).503 Service Unavailable The API service cannot process the request at this time (the service isunavailable—it is initializing, for example).Exception InformationEach errored response is accompanied by an exception message in the format requested by the client:XMLhttp response code numbererrcodehuman readable messageJSON{“response-code : “http response code number”“specific-error”: “errcode”“specific-msg” : “human readable message”}Note that this exception format contains redundant information (the HTTP response code). This can besafely ignored by most clients. Adobe Flash, however, does not pass responses for anything other thanHTTP 200 OK. To support these clients, the API supports the error code suppression as a query string:HTTP GET /v1.0/dataservice/inventory/devices?status=down&suppress_errors=trueRidgeline 4.0 REST API Quick Start 16

Authentication and ExceptionsIf this query string is supplied with a request, all responses report the HTTP status, 200 OK, allowingclients to access the actual HTTP error code within the response object. The suppression of errors is notenabled by default.Ridgeline 4.0 REST API Quick Start 17

4 Using the REST APIUsing the REST API through a BrowserUsing REST API through a Simple Java ProgramJava ProgramCode ExampleUsing the REST API through a BrowserTo use the REST API through a web browser:1 Ensure that Ridgeline 4.0 is running.2 Start a web browser, type the appropriate URL in the address bar, and then press ENTER.3 If you are prompted for logon credentials, type the user name and password that you use to log onto the Ridgeline client.NoteThe default user name and password is admin.Figure 1: Sample Browser Output

Using the REST APIUsing REST API through a Simple Java ProgramTo use the REST API through a simple Java program:1 Ensure that Ridgeline 4.0 is running.2 Compile the Java program (see Java Program on page 19).3 Run the Java program.The associated HTTP responses from running the Java program are stored in a file with the followingname format: DD_MM_YYYY_hh_mm_ss_Rest_Get.[xml/json]Java ProgramThe following code is for a simple Java program that you can use to access the REST API.import java.io.BufferedWriter;import java.io.FileWriter;import java.io.IOException;import java.text.SimpleDateFormat;import java.util.Date;import org.apache.http.HttpEntity;import org.apache.http.HttpResponse;import org.apache.http.HttpStatus;import org.apache.http.StatusLine;import org.apache.http.auth.AuthScope;import org.apache.http.auth.UsernamePasswordCredentials;import org.apache.http.client.ClientProtocolException;import org.apache.http.client.methods.HttpGet;import org.apache.http.impl.client.DefaultHttpClient;import org.apache.http.util.EntityUtils;public class RestHttpClient {private static final String xmlExtension = ".xml";private static final String jsonExtension = ".json";private DefaultHttpClient client = new DefaultHttpClient();private String Url = null;private String hostName;private int portNumber;private String userName;private String password;public RestHttpClient(String Url, String hostName, int portNumber,String userName, String password) {if (Url == null || Url.equals(""))throw new NullPointerException("Null URL");this.Url = Url;this.hostName = hostName;this.portNumber = portNumber;this.userName = userName;this.password = password;}private String httpGet() {HttpGet httpget = new HttpGet(this.Url);String response = null;client.getCredentialsProvider().setCredentials(Ridgeline 4.0 REST API Quick Start 19

Using the REST APInew AuthScope(this.hostName, this.portNumber),new UsernamePasswordCredentials(this.userName,this.password));}try {HttpResponse httpResponse = client.execute(httpget);StatusLine status = httpResponse.getStatusLine();if (status.getStatusCode() == HttpStatus.SC_OK) {HttpEntity entity = httpResponse.getEntity();if (entity != null) {response = EntityUtils.toString(entity);}} else {response = httpResponse.toString();}} catch (ClientProtocolException e) {e.printStackTrace();} catch (IOException e) {e.printStackTrace();} finally {httpget.releaseConnection();}return response;private boolean isXML() {boolean isXML = false;if (this.Url.trim().endsWith(RestHttpClient.xmlExtension)) {isXML = true;}return isXML;}private String getFileName() {SimpleDateFormat formatter = newSimpleDateFormat("dd_MM_yyyy_HH_mm_ss");StringBuilder fileName = new StringBuilder(formatter.format(newDate()));fileName.append("_Rest_Get");fileName.append(isXML() ? RestHttpClient.xmlExtension: RestHttpClient.jsonExtension);}return fileName.toString();private void writeToFile() {BufferedWriter writer = null;try {writer = new BufferedWriter(new FileWriter(getFileName()));String response = httpGet();writer.write(response);} catch (IOException e) {e.printStackTrace();} finally {try {if (writer != null)writer.flush();Ridgeline 4.0 REST API Quick Start 20

Using the REST API} catch (IOException e) {}}}e.printStackTrace();public static void main(String[] args) {RestHttpClient httpClient = new RestHttpClient("http://10.120.91.105:8080/v1.0/dataservice/inventory/device.json","10.120.91.105", 8080, "admin", "admin");}httpClient.writeToFile();}Code ExampleApplication definitionpackage com.extremenetworks.library;import javax.ws.rs.ApplicationPath;import javax.ws.rs.core.Application;@ApplicationPath("/dataservice")public class RestfulServiceApplications extends Application{}package com.extremenetwokrs.library;import javax.xm.bind.annotation.XmlRootElement;@XmlRootElementpbulic class Device {private String ip;private String name;public Device() {}public Device(String ipaddress, String name){this.ip = ipaddress;this.name = name;}public String getIp() {return ip;}public void setIp(String ip){this.ip = ip;}public String qetName() {return name;public void setName(String name) {}Ridgeline 4.0 REST API Quick Start 21

Using the REST API}package com.extremenetworks.library;import java.util.List;import javax.we.rs.GET;import javax.we.rs.Path;import javax.we.rs.Produces;import javax.we.rs.QueryParam;@Path("/devices")@Produces("text/xml")public interface DeviceManager{@GET@Path("/")public List all();//URL http://HOST:PORT/WEBCONTEXT/dataservice/device?ip=1.1.1.1@GET@Path("/device/{ip}")public Device getDevice(@QueryParam("ip") int deviceId);}package com.extremenetworks.library;import java.util.Arrays;import java.util.List;public class DeviceManagerBean implements DeviceManager{@Overridepublic List all() {return Arrays.asList(new Device("l.1.1.1", "Device 1"),new Device("2.2.2.2", "Device 2"));}@Overridepublic Device getDevice(int deviceId) {return new Device("1.1.1.1", "Device 1");}}Data URL : http://localhost:8080/extreme/dataservice/devicesOutput in XML---1.1.1.1Device 1-2.2.2.2Device 2Ridgeline 4.0 REST API Quick Start 22

Using the REST APIOutput in JSON[{"name":"Device 1", "ip":"1.1.1.1"},{"name":"Device 2","ip":"2.2.2.2"}]Ridgeline 4.0 REST API Quick Start 23