2010512028, 12:03 Introduction to REST API Search Q © Introduction to REST API Lesson Contents 1. Configuration 1.1. Router 1.2. Python 1.2.1. GET interface 1.2.2, PUT interface 2. Conclusion In this lesson, welll take a look at what a REST API is. First of all, what is an API? 10351 hitpssnetworklessons.comiscofcenp-encor-360-40 Vintreduction o-rest-ap wn2010512028, 12:03 Introduction to REST API 4 We, as network engineers usually use the command-line interface (CL!) or a GUI to configure or monitor our network devices. Parsing show and debug commands with scripts is difficult because these commands are for humans. To interact with applications or network devices, we can use an Application Programming Interface (API). ‘An API is a software interface which allows other applications to communicate with our application Roy T. Fielding describes REST in his dissertation (chapter 5). t's an acronym for REpresentational State Transfer: * Representational means we transfer the representation of a resource between a server and a client, We use a data format for this representation, typically JSON or XML. * State Transfer means that each operation with a REST API is self-contained. Each request carries (transfers) all information (state) to complete the operation. REST APIs typically use HTTP methods to retrieve or send information between applications. We use the same HTTP methods when we use a web browser to visit a website, but now we use them to interact with an application. HTTP has multiple rnethods, but these four are the most common ones: © * GET: A read-only method to retrieve a specified resource. * POST: Submits data to the specified resource to process. The POST method can also create new resources. * PUT: Updates the specified resource by replacing the existing data, * DELETE: Deletes the specified resource. HTTP is popular so you can use REST APIs in almost any programming language. I mentioned resource several times but didn’t explain exactly what a resource is. A resource is a “thing” you can access and receive or change its representation. On the web, this could be a document or image. With a REST API, it could be a row in a database. We access a resource with a Uniform Resource Locator (URL). That's right, the URLs we also use for websites. A quick example is the following URL: https: //192.168.1.1:55443/api/v1/interfaces/loopback@ We can use this URL to access the Loopback 0 resource on a router. Ill show you in a minute what that looks like in action, hitpssnetworklessons.comiscofcenp-encor-360-40 Vintreduction o-rest-ap 2132008/2023, 12:08 Introduction to REST API | want to visit that website! rG I want to —— retrieve the SS R1's interface a -———— JSON status! © An API must meet 6 guiding constraints if we want to call ita REST API. Another name for an API that meets all constraints is a RESTful service. Understanding these constraints in detail is essential for API developers. The 6 constraints are: * Client-server: The client and server are independent. They interact with each other through requests. that the client initiates. The server listens for requests and answers them. * Stateless: The server doesn't store any state about previous requests. For example, it doesn’t track if a client already requested a resource before. It also doesn't track which resources were requested by actient. * Cacheable: The server includes a version number in its messages. The client can use this to decide whether it should request a resource again or use the cached data. * Uniform interface: The interface is decoupled from the implementation. There are four sub- constraints: © Identification of resources: Each resource must be uniquely identifiable via a URI (Uniform Resource Identifier). hnps:networklessons.comiciscalecnp-encor-350-40 introduction o-est-api ana2008/2023, 12:08 Introduction to REST API 4 server's database, We have to use a representation and neutral data format. When a client wants to update a resource, it has to take the following steps: = Request a representation of the resource. * Update the representation with new data. = Send the representation of the resource to the server. Self-descriptive messages: Each message (request or response) must include enough information so the receiver can understand it. A message requires a media type (for example “application/json’) that tells the receiver how to parse the message. Hypermedia as the engine of application state (HATEOAS): You should be able to discover other areas of the API similar to how a user browses a website. A response from the API should include links to other parts of the API. This way, you can figure out how the API works without referring to external documentation. * Layered system: REST allows a layered system. You could deploy the API on one server and the data ‘on another server. You could add additional layers like a load-balancer in between the client and server. The client can't tell whether it's communicating with an intermediate or end server. Extra layers should not affect communications between the client and the server. * Code on demand (optional): This is an optional constraint. The server usually sends a static representation in SON or XML. The server can optionally include executable code to.a cient. An example is a Java applet or JavaScript. REST has no built-in security features, but if needed we can add these, For example, we can use HTTPS for encryption and usernames or tokens for authentication. 1. Configuration Enough theoretical talk for now. Let's see how we can use a REST API to monitor and configure a Cisco CSR1000v router. Here's the topology welll use: Gi0/2: Li 172.16.1.100 Ze/ TET hnps:networklessons.comiciscalecnp-encor-350-40 introduction o-est-api ana2010512028, 12:03 Introduction to REST API 1.1. Router Let's start with the router. This is a CSR1000v router running !OS XE 16.6.1: Ritshow version | include Version Cisco 10S XE Software, Version 16.06.01 Cisco 10S Software [Everest], Virtual XE Software (x86_64_LINUX_IOSD-UNIVERSALK9-M), Version 16.6.1, RELEASE SOFTWARE (#c2) Want to take a look for yourself? Here you'll find the startup configuration of each device. R1 ~ hitpssnetworklessons.comiscofcenp-encor-360-40 Vintreduction o-rest-ap 5132010512028, 12:03 Introduction to REST API 4 interface Loopback® ip address 1.1.1.1 255.255.255.255 interface Gigabitethernet2 ip address 172.16.1.10@ 255.255.255.0 negotiation auto no mop enabled nto mop sysid ip route 0.0.0.0 0.0.0.0 172.16.1.254 end First, we create a user that has full access to the router: Ri(config)#username admin privilege 15 password admin Also, we activate the shared management interface: R1(config)#virtual-service csr_mgnt Ri(config-virt-serv)#ip shared host-interface Gigabitethernet 2 R1(config-virt-serv)tactivate % Activating virtual-service ‘csr_mgmt', this might take a few minutes. Use ‘show virtual-service list’ for progress. This configuration is all we have to do to enable the REST API. There are some show commands we can use to verify if the REST API is up. The first two commands are to check the status of the virtual service: Riftshow virtual-service list Virtual Service List: Name Status Package Name hitpsnetworklessons.comiscofcenp-encor-360-40 Vinreductiono-rest-ap ana2010512028, 12:03 Introduction to REST API 4 Ifyou want more details, try this: Rifshow virtual-service detail name csr_mgmt Virtual service csr_mgnt detail state Activated Owner rosd Package information Name : dosxe-remote-ngmt.16.06.01.0va Path 1 bootflash:/iosxe-renote-mgnt.16.06.@1.ova Application Name 2 ¢sr_mgmt Installed version : 2017.6 Description CSR-MGHT Signing key type Cisco release key Method SHA-1 Licensing © Name : Not Available Version : Not Available Detailed guest status Process Status Uptime # of restarts nginx up e@Y OW aD @: 4:36 e climgr up ey OW eD O: 4:36 1 restful_api up eY eW @D a: 4:36 e fegicpa Down pnscag Down pnscdme Down Feature status Configuration Restful API Disabled, UP pNsc Disabled, Down hitpsnetworklessons.comiscofcenp-encor-360-40 Vinreductiono-rest-ap m32010512028, 12:03 Introduction to REST API 4 ethd: RX packets:8@7, TX packets:795 eth1: RX packets:29, TX packets:28 Coredump file(s): R1_climgr_67_20190925-@94834-UTC.core.gz, lost+found Activated profile name: None Resource reservation Disk : 756 MB Memory : 512 MB cpu 5% system CPU Attached devices Type Name Alias Nic ieobc_1 —_ieobe NIC dp_133net2 Disk _rootfs Disk Jopt/var © Disk Jopt/var/c Serial/shell serialo Serial/aux serial1 Serial/Syslog serial2 Serial/Trace serial3 Watchdog, watchdog-2 Network interfaces MAC address Attached to interface 54: 0E :00:0B:0C:02 ieobe_1 FA:16:3E:DA:62:4F VirtualPortGroup33 Guest interface Interface: eth1 ip address: 172.16.1.100/24 hitpsnetworklessons.comiscofcenp-encor-360-40 Vinreductiono-rest-ap ana2010512028, 12:03 Introduction to REST API Address/Mask Next Hop Int. Resource admission (without profile) : passed Disk space: 756HB Memory 2 512MB cpu 1 5% system CPU vcpus : Not specified ‘Another command is show renote-nanagement which gives a quick overview: Rifshow renote-management status Remote managenent release version: 2017.6 Process status Uptime # of restarts e nginx up ey OW @D O: 3: 3 e climgr up ey ew aD @: 3: 3 1 restful_api up ey ew eD @: 3:3 e fegicpa Down pnscag Down pnscdme Down Feature Status Configuration Restful API Disabled, UP pNsc Disabled, Down Network stats: etho: RX packets:554, TX packets:548 ethl: RX packets:29, TX packets:28 That's all we have to configure on our router. hitpssnetworklessons.comiscofcenp-encor-360-40 Vintreduction o-rest-ap ona2010512028, 12:03 Introduction to REST API 4 repository. 1.2.1. GET interface Let’s start with a simple example. The script has two functions: © get token © get interface First, we authenticate with the router using a username and password, When successful, we receive a token, We then use an HTTP GET method to retrieve information about the loopback 0 interface. Let's run the script: python get-interface.py We received token: VqtxSiHJpuRytNQYoTF2S1zFd]IRgmAPFBZM4v9h+gE= Here is the interface information: @ "kind": “object#interface", “description”: "", if-name": “Loopbacke", “proxy-arp": true, “subnet-masi "255.255.255.255", .cmp-unreachable” true, “ipvé-enable": false, "nat-direction": "", ‘cmp-redirects": true, p-address": "1.1.2.1", "verify-unicast-source": false, “type”: “Loopback” ‘The output above is looking good. The router reports the configuration of the loopback 0 interface. 4.2.2, PUT interface hitpssnetworklessons.comiscofcenp-encor-360-40 Vintreduction o-rest-ap ron2010512028, 12:03 Introduction to REST API * get_token * put interface The get_token function is the same as in our previous script. The put_interface function adds a header that, specifies that the payload is in JSON format. We then send the payload with our updated configuration to the router. python put-interface.py We received token: VatXSiHJpURytNQVoTF2S1zFdJIRgMAPFEZM4VSh+ge= The router responds with status code: 204 The router responds with a 204 status code. This status code means that the server successfully fulfilled the request and that there is no additional content to send. 2. Conclusion You have now learned what a REST API is and how to use it on the Cisco CSR1000v router. * ANAPIis a software interface so that applications can interact with our application. * REST is an architecture style, described in a dissertation by Roy T. Fielding, * AREST API is an API that meets 6 constraints. * Most REST APIs use HTTP methods and JSON or XML as the data format. * We used the HTTP GET method to retrieve interface information and the HTTP PUT method to update its configuration, hope you enjoyed this lesson. Feel free to leave a comment if you have any questions. Previous Lesson Next Lesson Introduction to Python Network Automation and) Orchestration ® Tags: API, SDN Forum Replies hitpssnetworklessons.comiscofcenp-encor-360-40 Vintreduction o-rest-ap 32010512028, 12:03 Introduction to REST API 4 |.am new to Python and starting my first lab. In my virtual lab | have 3 CSR1000v connected to Ubuntu device with Python 3 installed on it and they can talk to each others. | have no problems with the router config but when it gets to the script | have no idea where and how to write the script and how to push it to the router. Can you clarify the Python part please? Thank you Hany GQ werraes Hello Hany In order to get a good grasp of Python it would be a good idea to find an online tutorial there are literally hundreds ‘out there) that can get you started scripting. A suggestion would be to go to https://www.learnpython.org/ which is a start from scratch introduction that can give you the basics you need for scripting. But you can do your awn search and find the course that will be best for you. ‘Once complete, if you have specific questions about how to apply it to networking and your virtual lab, well be able to @ more specifically help you out. | hope this has been helpfull Laz Ey eros HiRene, iim getting the output below, when trying to activate esr_mgmt, “*May 6 19:20:30,764: %&VMAN-3-VIRT_INST_INTERFACE: Fo: van: Virtual Service[csr_mgrnt]: Network interfaces::The number of network interfaces required do not match the number configured::Number defined: 1, number configured: (0 *May 6 19:20:31,746: #VIRT_SERVICE-S-ACTIVATION. STATE: Failed to activate virtual service csr_mgmt ‘And I don't see the “ip shared host.interface” command available: hepsilfedn- forum networklessons.com/uploads/default/original/2X/3/34d2e0132026dd24542e4c767619b708ec98eFfc-png hitpssnetworklessons.comiscofcenp-encor-360-40 Vintreduction o-rest-ap rane2008/2023, 12:08 Introduction to REST API Thanks eepises Hetowws ‘Thats interesting... could be that the syntax is different for a particular feature depending on the 1OS being used. In the lesson, Rene is using a CSR1000v router running IOS XE 15.6.1, What device are you using? Laz Gi ribeirouls Hi tim running the version below on EVE-NG. | thinkit was the only image that was available for free on Cisco's website Routertsh ver Cisco 10S XE Software, Version 03.17.02 - Standard Support Release Cisco 10S Software, CSR1OOOV Sofware (486,64 LINUX IOSD-UNIVERSALKS-M), Version 15.41)82, RELEASE SOFTWARE 3) (fea) Thanks, Le $2 18 more replies! Ask a question or join the discussion by visiting our Community Forum Disclaimer Privacy Policy Support About © 2013 - 2023 NetworkLessons.com 52189 hnps:networklessons.comiciscalecnp-encor-350-40 introduction o-est-api ran