Module 1

Set Up Your Lab Environment

• With virtualization, virtual computers can operate and run within physical computers. These Computers are called
Virtual Machines (VMs).
• VMs are often called guests, and physical computers are often called hosts.
• Anyone with a modern computer and operating system can run virtual machines.

Linux for DevNet

• Linux has gained widespread use in servers, Internet of Things (IoT) devices, networking equipment, smartphones, and
many other devices that may not seem as even being computers.
• All coding labs in this course are performed on a Linux-based VM.

Python Programming
• Python is an easy to learn programming language.
• Few factors that make Python a great tool for learning basic coding are:
• It is easy to learn - the time needed to learn Python is shorter than for many other languages.
• It is easy to use for writing new software – it is possible to write code faster when using Python.
• It is easy to obtain, install and deploy - Python is free, open and multiplatform.
• Python provides a solid foundation and allows to learn other programming languages (for example, C++, Java, or C)
much easier and faster.

Module 2
What is DevNet?
DevNet is a fully-integrated developer program comprising a website, an interactive developer community, coordinated
developer tools, integrated discussion forums, and sandboxes. It consists of the following features:
• Learning Labs - Self-paced tutorials that covers topics from basic coding to using REST APIs with various technologies
• Sandboxes - Production-like development and testing environments for a host of technologies
• Code Exchange - A repository of sample code written by other developers
• Developer support - Support for developer related issues through tickets, live chats, and forums
• Developer documentation - A central location for all of the product developer API documentation

Getting Started with DevNet Resources

DevNet provides developers a starting point for all Cisco APIs, including API documentation, education, and developer
support.
To get an overview of DevNet, visit the DevNet Home page at developer.cisco.com
The site offers the following:

• Start Now
• Learning Tracks
• Video Course
• Sandbox
• Code Exchange
• Ecosystem Exchange

DevNet Learning Labs

DevNet Learning Labs provide:

• Tutorials – Cover engineering technologies, programming languages, and concepts such as model-driven
programmability, REST APIs, Python, and JavaScript.
• A walk-through for using a DevNet Sandbox - A pre-configured environment that is already installed with Cisco
platforms.
DevNet Learning Labs also enables you to:
• Set up a development environment - For practicing tasks on a local computer
• Mimic the overall DevNet site - Using tutorials on coding, collaboration, IoT, data centre, mobility (mobile and
wireless), and networking.
DevNet Exchanges
DevNet provides multiple ways for community members to share with each other. These are called Exchanges.

Currently, the following exchanges are available:

• Automation Exchange – This exchange provides a collection of network automation use cases with different solutions
and toolkits.
• Code Exchange – This exchange is a repository of source code or tools. It uses the GitHub API, as well as human
moderators, to categorize and display hundreds of related repositories.
• Ecosystem Exchange – In this exchange, one can find over 1,500 solutions across different technologies, industries,
and geographies to begin solution design and development.

Find a Use Case in Automation Exchange

• The Automation Exchange provides various use cases for network automation that include:
• Listing of data
• Adding configurations
• Activating policies across domains, users, or devices
• The listings are for different tool sets such as Ansible or Puppet, and different infrastructure scenarios, such as:
• Campus or Branch
• Data Centre
• Service Provider

DevNet Developer Support

DevNet offers developer support and can help troubleshoot integrations, API connections, and other specialty questions
about developer use cases on Cisco products.

Visit the website developer.cisco.com/support for more information.

One can get support by:
• Logging a ticket
• Posting to a community forum
• Accessing a WebEx Teams space

DevNet Developer Support

• Knowledge Base - Consists of troubleshooting articles for reference.
• Support Case - A case-based ticket used for one-on-one support with a response time of one business day.
• Forums in the Cisco Developer Community - To view community forums, visit https://devnetsupport.cisco.comand
click Community

Introduction
• The software development process is also known as the software development life cycle (SDLC).
• SDLC is more than just coding and also includes gathering requirements, creating a proof of concept, testing, and fixing
bugs.

Software Development Life Cycle (SDLC)

• SDLC is the process of developing software, starting from an idea and ending with delivery. This process consists of six
phases. Each phase takes input from the results of the previous phase.
• Although the waterfall methods is still widely used today, it's gradually being superseded by more adaptive, flexible
methods that produce better software, faster, with less pain. These methods are collectively known as “Agile
development.

Requirements and Analysis Phase

▪ The requirements and analysis phase involves exploring the stakeholders' current situation, needs and constraints,
present infrastructure, and so on, and determining the problem to be solved by the software.
▪ After gathering the requirements, the team analyzes the results to determine the following:
• Is it possible to develop the software according to these requirements, and can it be done onbudget?
• Are there any risks to the development schedule, and if so, what are they?
• How will the software be tested?
• When and how will the software be delivered?
▪ At the conclusion of this phase, the classic waterfall method suggests creating a Software Requirement
Specification (SRS) document, which states the software requirements and scope, and confirms this meticulously with
stakeholders.
Design
• During the Design phase, the software architects and developers design the software based on the provided SRS.
• At the end of the phase, the team creates High-Level Design (HLD) and Low-Level Design (LLD) documents.

Implementation
• The implementation phase is also called the coding or development phase.
• As all the components and modules are built during this phase, it is the longest phase of the life cycle.
• At the end of the phase, the functional code that implements all customer's requirements is ready to be tested.

Testing
• In this phase, code is installed in the test environment
• Functional testing, integration testing, performance testing and security testing is performed.
• Testing continues until all the codes are bug free and pass all the tests. At the end of this
phase, a high quality, bugfree, working piece of software is ready for production.

Deployment
• During this phase, the software is installed into the production environment.
• At the end of the phase, the product manager releases the final piece of software to end users.

Maintenance
• During the maintenance phase, the team:
• Provides support to customers
• Fixes bugs found in production
• Works on software improvements
• Gathers new requests from the customer
• At the end, the team works on the next iteration and version of the software

Software Development Methodologies

• A software development methodology is also known as Software Development Life Cycle model.
• The three most popular methodologies are:
• Waterfall
• Agile
• Lean

• The type of methodology to be used depends on the:

• Type of the project
• Length of the project
• Size of the team.

Waterfall Software Development

• The original waterfall model was created by Winston W. Royce.

• His original model consisted of seven phases:Agile Software Development
• Agile method is flexible and customer-focused.
• A group of 17 software developers came up with the Manifesto for Agile Software Development, also known as the

Agile Manifesto, in 2001. According to the Agile Manifesto, the values of Agile are:
• Individuals and interactions over processes and tools
• Working software over comprehensive documentation
• Customer collaboration over contract negotiation
• Responding to change over following a plan

• The Agile manifesto lists 12 different principles:

 Agile Manifesto Principles
 Customer focus
 Collaboration
 Working software
 Simplicity
 Embrace change and adapt
 Motivated teams
 Work at a sustainable Pace
 Self-organizing teams
 Frequent delivery of working software
 Face-to-face Conversations
 Agile environment
 Continuous Improvement

Agile Methods
The popular Agile methods are:
• Agile Scrum: The Scrum focuses on small, self-organizing teams that meet daily for short periods and work in iterative
sprints.
• Lean: The Lean method emphasizes on elimination of wasted effort in planning and execution, and reduction of
programmer cognitive load.
• Extreme Programming (XP): XP deliberately addresses the specific kinds of quality-oflife issues faced by the software
development teams.
• Feature-Driven Development (FDD): FDD prescribes that software development should proceed in terms of an overall
model, broken out, planned, designed, and built featureby-feature.

Agile Methods (Contd.)

Sprints
• A sprint is a specific period of time, usually between 2-4 weeks, during which, each team takes on as many tasks (also
known as user stories) as they feel they can accomplish. When the sprint is over, the software should be working and
deliverable.
• The duration of the sprint is determined before the process begins and should rarely change.

Backlog
• The backlog consists of all the features of the software, in a prioritized list.
• User stories
• A user story is a simple statement of what a user (or a role) needs, and why. Each user story should be small enough
that a single team can finish it within a single sprint.

• The suggested template for a user story is:

As a <user|role>, I would like to <action>, so that <value|benefit>

Scrum Teams
• Scrum teams are cross-functional, collaborative, self-managed and self-empowered.
• The scrum teams should not be larger than 10 individuals.
• The scrum master should have a daily stand-up meeting with the team at a fixed time everyday for not more than 15
minutes.
• The goal is to go over important tasks that have been finished, are in progress, or are about to be started.
Lean Software Development
• Lean software development is based on Lean Manufacturing principles, which are focused on minimizing waste and
maximizing value to the customer.
• The seven principles of lean, given in the book “Lean Software Development: An Agile Toolkit,” are as follows:
• Eliminate waste
• Amplify learning
• Decide as late as possible
• Deliver as fast as possible
• Empower the team
• Build integrity in
• Optimize the whole

Amplify Learning with Short Sprints

• To be able to fine tune a software, there should be frequent short iterations of working software. This enables the
following:
• Developers learn faster
• Customers can give feedback sooner
• Features can be adjusted so that they bring customers more value
•Decide as Late as Possible
• When there is uncertainty, it is best to delay the decision-making until as late as possible in the process.
This is because it is better to base decisions on facts rather than opinions or speculations.

Deliver as Fast as Possible

Enables customers to provide feedback
Doesn’t allow customers to change their mind
Enables developers to amplify learning
Makes everyone take decisions faster
Provides customers the required features
Produces less waste

Empower the Team

• Each person must be allowed to make decisions in the area of their own expertise.

Build Integrity In
• Integrity for the software is when the software addresses the customer’s needs as well as maintains the usefulness for
the customer.

Optimize the Whole

• The software must be built cohesively. The value of the software will suffer if each expert only focuses on their
expertise and doesn't consider the ramifications of their decisions on the rest of the software.

MODULE 3
Software Design Patterns
Introduction
• Software design patterns are best practice solutions for solving common problems in software development.
• Design patterns are language-independent.
• In 1994, Erich Gamma, Richard Helm, Ralph Johnson, and John Vlissides (known as the Gang of Four (GoF)) published a
book called Design Patterns - Elements of Reusable Object-Oriented Software.
Patterns identified are:
• Program to an interface, not an implementation.
• Favor object composition over class inheritance.
• Software design patterns have already been proven to be successful, so using them can speed up development.

The Original Design Patterns

• The Gang of Four divided patterns into three main categories:
• Creational
• Structural
• Behavioral
• They listed 23 design patterns.
• Two of the most commonly used design patterns are:
• The Observer design pattern (a Behavioral design pattern)
• The Model-View-Controller (MVC)

Observer Design Pattern

• The observer design pattern is a subscriptionnotification design that lets objects receive events when there are
changes to an object they are observing.
• To implement this subscription mechanism:
• The subject must have the ability to store a list of all of its observers.
• The subject must have methods to add andremove observers.
• The benefit of the observer design pattern is that observers can get real time data from the subject when a change
occurs.
• Subscription mechanisms always provide better performance than other options, such as polling.

Model-View-Controller (MVC)
• The Model-View-Controller (MVC) design pattern aims to simplify development of applications that depend on graphic
user interfaces.
• MVC abstracts code and responsibility into three different components:
• Model: The model is the application's data structureand is responsible for managing the data, logic and rules
of the application. It gets input from the controller.
• View: The view is the visual representation of the data.
• Controller: The controller is the middleman between the model and view. It takes in user input and
manipulates it to fit the format for the model or view.
• The benefit of MVC is that each component can be built in parallel.

Types of Version Control Systems

• Version control, also called version control systems, revision control or source control, is a way to manage changes to a
set of files in order to keep a history of those changes.
• Benefits of version control are:
• Enables collaboration
• Accountability and visibility
• Work in isolation
• Safety
• Work anywhere
• There are three types of version control systems:
• Local
• Centralized
• Distributed

Local Version Control System (LVCS)

• LVCS uses a simple database to keep track of all of the changes to the file.
• In most cases, the system stores the delta between the two versions of the file.
• When the user wants to revert to the file, the delta is reversed to get to the requested version.
Centralized Version Control System (CVCS)
• CVCS uses a server-client model.
• The repository is stored in a centralized location, on a server.
• In CVCS, only one individual can work on a particular file at a time.
• An individual must check out the file to lock it and make the required changes and check in once done.

Distributed Version Control System (DVCS)

• DVCS is a peer-to-peer model.
• The repository can be stored on a client system, but it is usually stored in a repository hosting service.
• In DVCS, every individual can work on any file, at the same time, because the local file in the working copy is being
modified. Hence, locking is not required.
• When the individual has made the changes, they push the file to the main repository that is in the repository hosting
service, and the version control system detects any conflicts between file changes

Git
• Git is an open source implementation of a distributed version control system that is currently the latest trend in
software development.
• A Git client must be installed on a client machine. It is available for MacOS, Windows, and Linux/Unix.
• One key difference between Git and other version control systems is that Git stores data as snapshots instead of
differences (the delta between the current file and the previous version).
• If the file does not change, Git uses a reference link to the last snapshot in the system instead of taking a new and
identical snapshot.

• Git is organized by 3s- three stages and three states.

• The three stages are:
• Repository (the .git directory)
• Working directory
• Staging area
• The three states are:
• Committed
• Modified
• Staged

Local vs. Remote Repositories

• Git has two types of repositories: local and remote.
• A local repository is stored on the file system of a client machine, which is the same one on which the git commands
are being executed.
• A remote repository is stored somewhere other than the client machine, usually a server or repository hosting service.
• A remote repository with Git continues to be a DVCS because the remote repository will contain the full repository,
which includes the code and the file history.
• When a client machine clones the repository, it gets the full repository without requiring to lock it, as in a CVCS.
• After the local repository is cloned from the remote repository or the remote repository is created from the local
repository, the two repositories are independent of each other until the content changes are applied to the other
branch through a manual Git command execution

What is Branching?
• Branching enables users to work on code independently without affecting the main code in the repository. When a
repository is created, the code is automatically put on a branch called Master.
• Branches can be local or remote, and they can be deleted and have their own history, staging area, and working
directory.
• Git's branch creation is lightweight, and switching between branches is almost instantaneous.
• When a user goes from one branch to another, the code in their working directory and the files in the staging area
change accordingly, but the repository (.git) directories remain unchange

GitHub and Other Providers

• Git and GitHub are not the same.
• While Git is an implementation of distributed version control and provides a command line interface, GitHub is a
service provided by Microsoft that implements a repository hosting service with Git.
• In addition to providing the distributed version control and source code management functionality of Git, GitHub
provides additional features such as:
• code review
• documentation
 • project management
• bug tracking
• feature requests
• GitHub introduced the concept of the ‘pull request’, which is a way of formalizing a request by a contributor to review
changes such as new code, edits to existing code, etc., in the contributor's branch for inclusion in the project's main or
other curated branches

Git Commands
Setting up Git
• To configure Git, use the --global option to set the initial global settings.
Command: git config --global key value
Create a New Git Repository
• Git provides a git init command to create an empty Git repository, or make an existing folder a Git repository.
• When a new or existing project becomes a Git repository, a hidden .git directory is created inthat project folder.
• The .git directory is the repository that holds the metadata such as the compressed files, the commithistory, and the
staging area. In addition, Git also creates the master branch.

Command: git init

• To make a new or existing project a Git repository, use the following command:$ git init <project directory>where the
<project directory> is the absolute or relative path to the new or existing project.
• For a new Git repository, the directory in the provided path will be created first, followed by the creation of the .git
directory.
Get an Existing Git Repository
• Command: git clone <repository> [target directory]where <repository> is the location of the
repository to clone.
• Git supports four major transport protocols for accessing the <repository>: Local, Secure Shell (SSH), Git, and HTTP.

Clean Code
• Clean codes are the result of developers trying to make their code easy to read and understand for other developers.
• They follow some common principles related to formatting, organization, intuitiveness of components, purpose and
reusability.
• Clean codes emphasize on standardization, proper organization, modularity, providing inline comments and other
characteristics that help make code self-documenting.
Reasons why developers want to write clean code
• Clean code is easier to understand, more compact, and better-organized.
• Clean code, being modular, tends to be easier to test using automated methods such as unit testing frameworks.
• Clean code, being standardized, is easier to scan and check using automated tools.
• It simply looks nicer.

Methods and Functions

• Methods and Functions are blocks of code that perform tasks when executed.
• Following are some standard best-practices for determining whether a piece of code should be encapsulated (in a
method or function):
• Code that performs a discrete task, even if it happens only once, may be a candidate for encapsulation.
• Task code that is used more than once should probably be encapsulated.
• Methods and Functions can be written once and executed as many times as required.
• If used correctly, methods and functions will simplify the code, and reduce the potential for bugs.

Arguments and Parameters

• Arguments and parameters add flexibility to methods and functions.

Return Statements
• The return statement refers to the return value that is specified using the keyword return followed by a variable or
expression. A return statement ends the execution of a function, and returns control to the calling function.
• When a return statement is executed, the value of the return statement is returned and any code below it gets
skipped.

Methods are code blocks associated with an object, typically for object-oriented programming.
Functions are standalone code blocks.
Modules
• Developers typically use modules to divide a large project into smaller parts so that the code can be read and
understood easily.
• They consists of a set of functions and typically contains an interface for other modules to integrate with.
• A module is packaged as a single file and is expected to work independently.
• Below is a module with a set of functions saved in a script called circleClass.py.

Classes
• In most Object-Orient Programming (OOP) languages, and in Python, classes are a means of bundling data and
functionality. Each class declaration defines a new object type.
• Classes may have class variables and object variables.
• New classes may be defined, based on existing, previously defined classes, so that they inherit the properties, data
members, and functionality (methods).
• A class may be instantiated (created) multiple times, and each with its own object-specific data attribute values.
Note: Unlike other OOP languages, in Python, there is no means of creating 'private' class variables or
internal methods. However, by convention, methods and variables with a single preceding underscore
( _ ) are considered private and not to be used or referenced outside the class.

What is a Code Review and Why Should You Do This?

• A code review is when developers look over the codebase, a subset of code, or specific code changes and provide
feedback. These developers are often called reviewers.
• The code review process only happens after the code changes are complete and tested.
• The goal of code reviews is to make sure that the final code:
• Is easy to read
• Is easy to understand
• Follows coding best practices
• Uses correct formatting
• Is free of bugs
• Has proper comments and documentation
• Is clean

The most common types of code review processes

include:
• Formal code review: Developers have a series of meetings to review the whole codebase.
• Change-based code review: Also known as a tool-assisted code review, reviews code that was changed as a result of a
bug, user story, feature, commit, and so on.
• Over-the-shoulder code review: A reviewer looks over the shoulder of the developer who wrote the code and
provides feedback.
• Email pass-around: It can occur following the automatic emails sent by the source code management systems when a
checkin is made.

Testing
• Software testing is classically subdivided into two general categories:
• Functional testing seeks to determine whether the software works correctly. Does it behave as intended in a
logical sense, from the lowest levels of detail examined with Unit Testing, to higher levels of complexity explored
in Integration Testing?
• Non-functional testing examines usability, performance, security, resiliency, compliance, localization, and
many other issues. This type of testing finds out if the software is fit for its purpose, provides the intended value,
and minimizes risk.
• Developers capture design requirements as tests and then write software to pass those tests. This is called Test-Driven
Development (TDD).

Unit Testing
• Detailed functional testing of small pieces of code (lines, blocks, functions, classes, and other components in isolation)
is called Unit Testing.
• These test frameworks are software that allows you to make assertions about testable conditions and determine if
these assertions are valid at a point in execution.

Integration Testing
• Integration testing ensures that all the individual units fit together properly to make a complete application.
Test-Driven Development (TDD)
• If you want to test to validate the application design in light of requirements, implies that you should write the testing
code before you write the application code .
• Having expressed the requirements in your testing code, you can then write the application code until it passes the
tests that you have created in the testing code.
• The basic pattern of TDD is a five-step, repeating process:
• Create a new test.
• Run tests to see if any fail for unexpected reasons.
• Write application code to pass the new test.
• Run tests to see if any fail.
• Refactor and improve application code.

Data Formats
• Rest APIs let you exchange information with remote services and equipment.
• The three most popular standard formats for exchanging information with remote APIs are XML, JSON, and YAML.
• Parsing XML, JSON, or YAML is a frequent requirement of interacting with APIs. An oftencountered pattern in REST API
implementations is as follows:
• Authenticate, usually by POSTing a user/password combination and retrieving an expiring token for use in
authenticating subsequent requests.
• Execute a GET request to a given endpoint (authenticating as required) to retrieve the state of a resource,
requesting XML, JSON, or YAML as the output format.
• Modify the returned XML, JSON, or YAML.
• Execute a POST (or PUT) to the same endpoint (again, authenticating as required) to change the state of the
resource, again requesting XML, JSON, or YAML as the output format and interpreting it as needed to determine
if the operation was successful.

XML
• Extensible Markup Language (XML) is a generic methodology for wrapping textual data in symmetrical tags to indicate
semantics.
• It is a derivative of Structured, Generalized Markup Language (SGML), and also the parent of HyperText Markup
Language (HTML). XML filenames typically end in ".xml".

•XML Document Body: Except the first two lines of a XML document, the remainder of the
document is considered as the body.
• User-Defined Tag Names: XML tag names are user-defined. If you are composing XML for
your own application, pick tag names that clearly express the meaning of data elements, their
relationships, and hierarchy.
• Special Character Encoding: Data is conveyed in XML as readable text.
• XML Prologue: The XML prologue is the first line in an XML file.
• Comments in XML: XML files can include comments, using the same commenting convention
used in HTML documents.
• XML Attributes: XML lets you embed attributes within tags to convey additional information.
XML Namespaces:
• Namespaces are defined by the IETF and other internet authorities, organizations, and other entities, and their
schemas are typically hosted as public documents on the web.
• Namespaces are identified by Uniform Resource Names (URIs) to make persistent documents reachable
without the seeker needing to be concerned about their location.
• The code example below shows the use of a namespace, defined as the value of an xmlns attribute, to assert
that the content of an XML remote procedure call should be interpreted according to the legacy NETCONF 1.0
standard.

Interpreting XML
• In the XML Namespaces example, the structure is represented as a list or onedimensional array (called 'instances') of
objects (each identified as an 'instance' by
bracketing tags). Each instance object contains two key-value pairs denoting a unique instance ID and VM server type.

JSON
• JSON, or JavaScript Object Notation, is a data format derived from the way complex object literals are written in
JavaScript.
• JSON filenames typically end in “.json.”
•JSON Basic Data Types: JSON basic data types include numbers, strings, Booleans, or nulls.
• JSON Objects: As in JavaScript, individual objects in JSON comprise of key/value pairs, which may be surrounded by
braces, individually.
• JSON Maps and Lists: In this case, each individual key/value pair does not need its own set of brackets, but the entire
object does. JSON compound objects can be deeply-nested, with complex structure. It can also express JavaScript
ordered arrays (or 'lists') of data or objects.
• No Comments in JSON: Unlike XML and YAML, JSON does not support any kind of standard method for including
unparsed comments in code.
• Whitespace Insignificant: Whitespace in JSON is not significant, and files can be indented using tabs or spaces as
preferred, or not at all.

YAML
• YAML Ain't Markup Language (YAML) is a superset of JSON designed for even easier human readability.
• As a superset of JSON, YAML parsers can generally parse JSON documents (but not viceversa).
• Hence, YAML is better than JSON at certain tasks, including the ability to embed JSON directly (including quotes) in
YAML files.

YAML File Structure: YAML files conventionally open with three dashes ( --- alone on a
line) and end with three dots ( ... likewise).
• YAML Data Types: YAML basic data types include numbers, strings, Booleans, or nulls.
• Basic Objects: In YAML, basic data types are equated to keys.
• YAML Indentation and File Structure: YAML indicates its hierarchy using indentation.
• Maps and Lists: YAML easily represents more complex data types, such as maps
containing multiple key/value pairs and ordered lists.
• Maps are generally expressed over multiple lines, beginning with a label key and a
colon, followed by members, indented on subsequent lines:
•Lists (arrays) are represented with optionally-indented members preceded by a single dash and space:
•Maps and lists can also be represented in a so-called "flow syntax," which looks very much like JavaScript or
Python:
Long Strings: They are represented using a 'folding' syntax, where linebreaks are presumed to be replaced by spaces
when the file is parsed/consumed, or in a non-folding syntax.
Comments: Comments in YAML can be inserted anywhere except in a long string literal, and are preceded by the hash
sign and a space.
More YAML Features: YAML has many more features, most often encountered when using it in the context of specific
languages, like Python, or when converting to JSON or other formats. For example, YAML 1.2 supports schemas and tags,
which can be used to disambiguate interpretation of values.
For example, to force a number to be interpreted as a string, you could use the !!str string,
which is part of the YAML "Failsafe" schema:

Parsing and Serializing

• Parsing means analyzing a message, breaking it into its component parts, and understanding their purposes in context.
• Serializing is roughly the opposite of parsing.
• Popular programming languages such as Python generally incorporate easy-to-use parsing functions that can accept
data returned by an I/O function and produce a semanticallyequivalent internal data structure containing valid typed
data.
• On the outbound side, they contain serializers that turn internal data structures into semantically-equivalent messages
formatted as character strings.
MODULE 4
What is an API?
• An Application Programming Interface (API) allows one piece of software talk to another.
• It uses common web-based interactions or communication protocols and its own proprietary standards.
• An API determines what type of data, services, and functionality the application exposes to third parties.
• By providing APIs, applications can control what they expose in a secure way

Why use APIs?

• APIs are built to be consumed programmatically by other applications and they can also be used by humans who want
to interact with the application manually.
Use cases of APIs are as follows:
• Automation tasks – Build a script that performs manual tasks automatically and programmatically.
• Data integration – An application can consume or react to data provided by another application.
• Functionality – An application can integrate another application's functionality into its product.

Why are APIs so popular?

• APIs have existed for decades, but exposure and consumption of APIs has grown exponentially in the last 10 years or
so.
• Most modern APIs are designed into the product and are thoroughly tested.
• Simplified coding languages such as Python have made it possible for non-software engineers to build applications and
consume APIs.

Types of Design Styles

• A product’s set of APIs may consist of both synchronous and asynchronous designs, where each API’s design is
independent of the others.
• The application consuming the API manages the response differently depending on the API design.

Synchronous APIs
• Synchronous APIs respond to a request directly by providing data immediately.
When are APIs synchronous?
• APIs are synchronous when the data for the request is readily available.
Benefits of a synchronous API design
• Synchronous APIs enable the application to receive data immediately. If the API is designed correctly, the application
performance will be better.
Client side processing
• The application that is making the API request must wait for the response before performing any additional code
execution tasks.

Asynchronous APIs
• Asynchronous APIs provide a response (with no data) to signify that the request has been received.
When are APIs asynchronous?
• APIs are asynchronous when the request takes some time for the server to process or if data isn’t readily available.
Benefit of asynchronous API design
• Asynchronous APIs allow the application to continue execution without being blocked till the server processes the
request, thus resulting in better performance.
Client-side processing
• With asynchronous processing, the design of the API on the server side defines the requirement on the client side.

Common Architectural Styles

• There are certain standards, protocols, and specific architectural styles which make it easier for consumers of the API
to learn and understand the API.
• The three most popular types of API architectural styles are :
• RPC
• SOAP
• REST

Remote Procedure Call (RPC)

• Remote Procedure Call (RPC) is a request-response model that allows an application to make a procedure call to
another application.
• When RPC is called to a client, the method gets executed and the results get returned.
• RPC is an API style that can be applied to different transport protocols such as:
 • XML-RPC
• JSON-RPC
• NFS (Network File System)
• Simple Object Access Protocol (SOAP)

Simple Object Access Protocol (SOAP)

• Simple Object Access Protocol (SOAP) is a XML- based messaging protocol. It is used for communication between
applications on different platforms or built with different programming languages.
SOAP is:
• Independent: All applications can communicate with each other and run on different operating systems
• Extensible: Add features such as reliability and security
• Neutral: Can be used over any protocol, including HTTP, SMTP, TCP, UDP, or JMS
A SOAP message is an XML document that may contain the following four elements:
• Envelope – the root element of XML document.
• Header - contains application-specific information such as authorization, SOAP-specific attributes and so on
• Body - contains the data to be transported to the recipient
• Fault - provides error and/or status information

REpresentational State Transfer (REST)

• REpresentational State Transfer (REST) is an architectural style authored by Roy Thomas Fielding.
• Roy has established six constraints that can be applied to any protocol in REST
Client-server
• The client and server should be independent of each other.
• This will enable the client to be built for multiple platforms which will simplify the server side components.

Stateless
• Requests from the client to the server must contain REST client-server model and all the information which the server
needs to make the request.
• The server cannot contain session states.

Cache model:
• Responses from the server must state whether the response is cacheable or non-cacheable.
• If it is cacheable, the client can use the data from the response for later requests.

Uniform interface:
The interface between the client and the server adhere to the four principles:
• Identification of resources
• Manipulation of resources through representations
• Self-descriptive messages
• Hypermedia as the engine of application state.

Layered system:
• The Layered system consists of different hierarchical layers in which each layer provides services only to the layer
above it.
• As a result, it consumes services from the layer below.

Code-on-demand:
• The information returned by a REST service can include executable code (for example, javascript) or links intended to
usefully extend client functionality.
• The constraint is optional because execution of third-party codes introduces potential security risks.

REST Web Service APIs

• A REST Web service API (REST API) is a programming interface that communicates over HTTP.
• REST APIs use the same concepts as the HTTP protocol which are as follows:
• HTTP requests/responses
• HTTP verbs
• HTTP status codes
• HTTP headers/body

REST API Requests

• REST API requests are HTTP requests that are a way for an application (client) to ask the server to perform a function.
• REST API requests are made up of four major components:
• Uniform Resource Identifier (URI)
• HTTP Method
• Header
• Body

The Uniform Resource Identifier (URI), also referred to as Uniform Resource Locator (URL), identifies which resource the
client wants to manipulate. The components of a URI are:
• Scheme: specifies which HTTP protocol should be used, http or https.
• Authority: consists of two parts, namely, host and port.
• Path: represents the location of the resource, the data or object, to be manipulated on the server.
• Query: provides additional details for scope, filtering, or to clarify a request

HTTP method:
• REST APIs use the standard HTTP methods to communicate to the web services for which action is being requested for
the given resource.
• The suggested mapping of the HTTP Method to the action is as follows:

HTTP Method Action Description

POST Create Create a new object or resource.
GET Read Retrieve resource details from the system.
PUT Update Replace or update an existing resource.
PATCH Partial Update Update some details from an existing resource.
DELETE Delete Remove a resource from the system.

Header:
• HTTP headers are formatted as name-value pairs that are separated by a colon ( : ), [name]:[value].
Two types of headers:
 Request headers - Include additional information that does not relate to the content of the message.
 Entity headers - Additional information that describes the content of the body of the message

Body:
• The body of the REST API request contains the data pertaining to the resource that the client wants to manipulate.
• REST API requests that use the HTTP method POST, PUT, and PATCH typically include a body.
• The body is optional depending on the HTTP method.
• If the data is provided in the body, then the data type must be specified in the header using the Content-Type key

REST API Responses

• REST API responses are HTTP responses that communicate the results of a client's HTTP request.
• REST API Responses are made up of three major components:
• HTTP Status
• Header
• Body

HTTP Status
• The HTTP status code help the client determine the reason for the error and can sometimes provide suggestions for
fixing the problem.
• HTTP status codes consists of three digits, where the first digit is the response category and the other two digits are
assigned in numerical order.
• There are five different categories of HTTP status codes:
• 1xx – Informational – for informational purposes, responses do not contain a body
• 2xx – Success – the server received and accepted the request
• 3xx – Redirection – the client has an additional action to take to get the request completed
• 4xx -- Client Error – the request contains an error such as bad syntax or invalid input
• 5xx -- Server Error – unable to fulfill the valid requests.

HTTP Status Code Status Message Description

200 Ok Request was successfully and typically contains a payload (body)
201 Created Request was fulfilled and the requested resource was created
202 Accepted Request has been accepted for processing and is in process
400 Bad Request Request will not be processed due to an error with the request
401 Unauthorized Request does not have valid authentication credentials to perform the request
403 Forbidden Request was understood but has been rejected by the server
404 Not Found Request cannot be fulfilled because the resource path of the request was not
 found on the server
500 Internal Server Error Request cannot be fulfilled due to a server error
503 Service Unavailable Request cannot be fulfilled because currently the server cannot handle the
request

Header – The header in the response is to provide additional information between the server and the client in the name-
value pair format that is separated by a colon header[name]:[value].There are two types of headers: response headers
and entity headers.
• Response headers – It contains additional information that doesn't relate to the content of the message. The
typical response headers for a REST API request include: Set-Cookie and Cache-Control
• Entity headers – They are additional information that describes the content of the body of
the message. One common entity header specifies the type of data being returned: Content-Type

Response Pagination
• Response Pagination enables data to be broken into chunks.
• Most APIs that implement pagination use the query parameter to specify which page to return in the response.
Compressed response data
• Compressed data reduces large amount of data that cannot be paginated
• To request a data compression, the request must add the Accept-Encoding field to the request header. The accepted
values are:
• gzip
• compress
• deflate
• br
• identity

Using Sequence Diagrams with REST API

• Sequence diagrams are used to explain a sequence of exchanges or events.
• API request sequence diagram has three separate sequences:
• Create session- the starting request is labeled as HTTPS: Create Session w/credentials.
• Get devices - request a list of devices from the platform.
• Create device – begins with a POST request to create a device.

REST API Authentication

• REST APIs require authentication so that random users cannot access, create, update, or delete information incorrectly
or maliciously.
• Some APIs that do not require authentication are read-only and they do not contain any critical or confidential
information.

Authentication Vs. Authorization

Authentication:
• Authentication proves the user’s identity.
• For example, when you go to the airport, you have to show your government-issued identification or use biometrics to
prove that you are the person you claim to be.
Authorization:
• Authorization defines the user access.
• It is the act where the user is proving to have permissions to perform the requested action on that resource.
• For example, when you go to a concert, all you need to show is your ticket to prove that you are allowed in.

Authentication mechanisms
The common types of authentication mechanisms include:
• Basic authentication: It transmits credentials as username/password pairs separated with a colon (:) and encoded
using Base64.
• Bearer authentication: It uses a bearer token, which is a string generated by an authentication server such as an
Identity Service (IdS).
• API Key: It is a unique alphanumeric string generated by the server and assigned to a user. The two types of API keys
are public and private.

Authorization Mechanisms
• Open Authorization (Oauth) combines authentication with authorization.
• Oauth was developed as a solution to insecure authentication mechanisms.
• Oauth has increased security as compared to other options.
• There are two versions of Oauth - OAuth 1.0 and OAuth 2.0, where OAuth 2.0 is not backwards compatible.
• OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service.
• OAuth allows the user to provide credentials directly to the authorization server [Identity Provider (IdP) or an Identity
Service (IdS)], to obtain an access token to share with the application.
• The process of obtaining the token is called a flow.

What are Rate Limits?

• An API rate limit is a way for a web service to control the number of requests a user or an application can make per
defined unit of time.
• Rate limiting helps to :
• avoid a server overload from too many requests at once
• provide better service and response time to all users
• protect against a Denial-of-Service (DoS) attack

Rate Limit Algorithms

Leaky bucket
• This algorithm puts all incoming requests into a request queue in the order in which they were received.
• The incoming requests can come in at any rate, but the server will process the requests from the queue at a
fixed rate.
• If the request queue is full, the request is rejected
Token bucket
• This algorithm gives each user a defined number of tokens they can use within a certain increment of time.
• When the client makes a request, the server checks the bucket to make sure it contains at least one token. If
so, it removes that token and processes the request. If there isn't a token available, it rejects the request.
• The client must calculate the number of tokens he currently has to avoid rejected requests
Fixed window counter
• In fixed window counter algorithm, a fixed window of time is assigned a counter to represent how many
requests can be processed during that period.
• When the server receives a request, the counter for the current window of time must be zero.
• When the request is processed, the counter is deducted. If the limit for that window of time is met, all
subsequent requests within that window of time will be rejected.
Sliding window counter
• This algorithm allows a fixed number of requests to be made in a set duration of time.
• When a new request is made, the server counts how many requests have already been made from the
beginning of the window to the current time to determine if the request should be processed or rejected.
• The client needs to ensure that the rate limit does not exceed at the time of the request.

Knowing the Rate Limit

• Many rate limiting APIs add details about the rate limit in the response's header.
• The commonly used Rate Limit keys include:
• X-Rate Limit-Limit - The maximum number of requests that can be made in a specified unit of time.
• X-Rate Limit-Remaining - The number of pending requests that the requester can make in the current rate limit
window
• X-Rate Limit-Reset - The time when the rate limit window will reset.

Exceeding the Rate Limit

• When the rate limit is exceeded, the server automatically rejects the request and sends back an HTTP response to the
user.
• The response containing the ‘rate limit exceeded’ error also includes a meaningful HTTP status code.
• The most commonly used HTTP status codes are 429: Too Many Requests or 403: Forbidden.

What is a Webhook?
• A Webhook is an HTTP callback, or an HTTP POST, to a specified URL that notifies the application when a particular
activity or event is occurred in the resources.
• With webhooks, applications are more efficient as polling mechanisms are not required.
• Webhooks are also known as reverse APIs, because applications subscribe to a webhook server by registering with the
webhook provider.
• Multiple applications can subscribe to a single webhook server.
Examples:
• The Cisco DNA Center platform provides webhooks that enable third-party applications to receive network data when
specified events occur.
• You can create a webhook to have Cisco Webex Teams notify you of new messages posted in a particular room

Consuming a Webhook
• In order to receive a notification from a webhook provider, the application must meet certain requirements:
• The application must be running at all times to receive HTTP POST requests.
• The application must register a URI on the webhook provider.
• Also, the application must handle the incoming notifications from the webhook server.
• Use free online tools to ensure the application is receiving notifications from a webhook.

Troubleshooting REST API Requests

• There will be instances where you will make an API request but will not get the expected
response. Hence, learning to troubleshoot the most common REST API issues is important.
• Always have the API reference guide and API authentication information handy while
troubleshooting the REST API issues.

No Response and HTTP Status Code from the API server

• Sometimes API servers cannot be reached or fail to respond. You can identify what went wrong from the error
messages received as a result of the request.
Troubleshooting tips for client side error:
• User error: Mistyping the URI when using the API for the first time.
• Invalid URI Example – To test the invalid URI condition, run a script which makes the request to a URI that is missing
the scheme
•Wrong Domain name Example – To test the wrong domain name condition, run a script
which simply makes the request to a URI that has the wrong domain name.
Connectivity Issues
• Are there any Proxy, Firewall or VPN issues?
• Is there an SSL error?
Invalid Certificate Example
• This issue can only occur if the REST API URI uses a secure connection (HTTPS).
• When the scheme of the URI is HTTPS, the connection will perform an the SSL handshake between the client and the
server. If it fails, fix the invalid certificate

Interpreting Status Codes

• The status code is a part of HTTP/1.1 standard (RFC 7231), where the first digit defines the
class of the response and the last two digits do not have any class or categorization role.
• The five categories of status codes are as follows:
• 1xx: Informational - Request received, continuing to process.
• 2xx: Success - The action was successfully received, understood, and accepted.
• 3xx: Redirection - Further action must be taken in order to complete the request.
• 4xx: Client Error - The request contains bad syntax or cannot be fulfilled.
• 5xx: Server Error - The server failed to fulfill an apparently valid request.
• Steps to troubleshoot errors:
• Check the return code - It can help to output the return code in the script during the
development phase.
• Check the response body - Output the response body during development
• Use status code reference – If the issues cannot be resolved by checking the return
code and response body

2xx and 4xx Status Codes

• 2xx – Success error: Successfully received, understood and accepted
• 4xx – Client side error: Error is on the client side.

Troubleshooting common 4xx errors:

400 – Bad request
The request could not be understood by the server due to malformed syntax, which is mainly due to:
• Misspelling of resources
• Syntax issue in JSON object

401 – Unauthorized:
• This error message means the server could not authenticate the request.
• Check your credentials, including username, password, API key, token, request URI

403 – Forbidden
• The server recognizes the authentication credentials, but the client is not authorized to
perform the request.

407 - Proxy Authentication Required

• This code is similar to 401 (Unauthorized), but it indicates that the client must first authenticate itself with the proxy.
• In this scenario, there is a proxy server between the client and the server, and the 407 response code indicates that
the client needs to authenticate with the proxy server first.

409 - The request could not be completed due to a conflict with the current state of the
target resource.
• For example, an edit conflict where a resource is being edited by multiple users would cause a 409 error.
• Retrying the request later might succeed, as long as the conflict is resolved by the server

415 - Unsupported Media Type

• In this case, the client sent a request body in a format that the server does not support.

5xx Status Codes

500 - Internal Server Error - The server encountered an unexpected condition that prevented it from fulfilling the
request.
501 - Not Implemented- The server does not support the functionality required to fulfill this request
502 - Bad Gateway - The server (acting as gateway or proxy) received an invalid response from an inbound server.
503 - Service Unavailable - The server is currently unable to handle the request due to overload or scheduled
maintenance.
504 - Gateway Timeout- The server (acting as a gateway or proxy) did not receive timely response from an upstream
server.