Using API For ACI Tshoot
Using API For ACI Tshoot
Enrique Estrada
TAC ACI
Agenda
• Introduction
• What is REST?
• What is the ACI MIT?
• ACI RESTful API
• Api Inspector
• Visore
• CLI/Moquery
• POSTMAN
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 2
What is REST? • Introduction
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 3
What is REST?
• REST or Representational State Transfer software architecture that
acts as an interface to manipulate resources on a Web Server.
• The REST calls are done over TCP connections using text.
• REST uses staless connection. This means each connection is done
in isolation to the others
• In order to manipulate the resources, REST has a set of predefined
operations:
• POST PUT
• GET DELETE
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 4
What is REST?
• GET
• Reading operation, obtains the resource defined in the query (the
URI of the Request)
• When a client sends a GET, it can expect these HTTP codes:
• 200 OK
• 404 Error in sintax
• 401 Authentication is needed
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 5
What is REST?
• POST
• This operation creates resources, the Resource to be created can be
part of URI or Body
• The result of this operation willl return any of these HTTP codes:
• 201 Created, The resource has been created
• 401 Unauthorized, the client needs authentication
• 404 Not found, likely a syntax issue
• 409 Clonfict, in case the operation creates a conflict with current state of
the target resource.
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 6
What is REST?
• PUT
• This operation updates the state of a resource in the Server
• The result of this operation could return this HTTP codes:
• 200 OK, The resource was successfullly updated
• 404 Not found, likely the resource specified in the request is not valid
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 7
What is REST?
• DELETE
• This operation erases the specified resource in the Server
• The result of this operation could return this HTTP codes:
• 200 OK, The resource was successfullly updated
• 404 Not found, check syntax
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 8
What is REST?
• ACI enables users to manipulate MO’s with these REST operations.
• GET – We can read the state of any MO by Dn or Class
• POST – Allows the user to create one or multiple MO by specifying
its attributes in the HTTP body
• DELETE – Allows for the deletion of the MO Dn defined in the
request
• For the next examples the app Postman will be used:
https://www.getpostman.com/
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 9
What is MIT? • Introduction
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 10
What is MIT?
• Management Information Tree, MIT
• ACI provides an Object-Oriented approach for the definition of the
Fabric.
• This is done by an abstraction of all components and services, from
the Power supply and Routing protocols to Statistics on Interfaces.
• These abstractions are placed under a unified hierarchy, forming the
MIT.
• The fabric state is saved in what is called Policy model
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 11
What is MIT?
• The policy model in the Apic is called logical model
• The policy model in the Switches is called concrete model
• The Apic exposes the logical model to the user and resolves the
concrete model for the switches
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 12
What is MIT?
• The abstraction representing a configuration, component or state are placed in logical
containers called MO or Managed Object
• The MO represent a resource in the MIT.
• Each MO is placed hiearchically based on a defined structrure.
e.g The Linecard MO exists under the Chassis MO
• In the Tree structure, there will be always a root MO for it.
• The children MOs will be nodes in the tree
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 13
What is MIT?
• The MOs can inherit characteristics from others.
• The different kind of MOs are grouped into classes.
• Each Class will be defined in the APIC documentation:
https://<APIC-IP>/doc/html/
• The documentation will show the inheritance:
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 14
What is MIT?
• All of the MOs derive from the namingNamedObject and TopProps
Classes their basic attributes like Dn and Rn
• Distinguished Name – Uniquely identifies the MO instance in the
fabric. In unix terms is the same as absolute path.
• Relative Name – Identifies the MO from its Parent MO. Relative path
in unix terms.
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 15
What is MIT?
• The MIT is deployed as a unix filesystem.
• Common Unix commands to navegate in a fs will work in the Apic
Cli(pwd,cd,ls, cat,|, grep, etc)
admin@mpod-apic1:node-102> pwd
• Each MO folder will have a file /home/admin/mit/topology/pod-1/node-102
admin@mpod-apic1:node-102> ls
mo ndbgs statexpst summary sys web
called summary which contains admin@mpod-apic1:node-102> cat summary
# Fabric Node
its attributes. id
adSt
: 102
: on
address : 10.0.136.66
• The other folders in the MO dn
name
: topology/pod-1/node-102
: ACI-MX-POD4-L102
rn : node-102
belong to child objects vendor : Cisco Systems, Inc
version : n9000-14.2(2e)
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 16
What is MIT?
• The ACI API allows access to the MIT with a RESTful interface
• The interface can be access by:
• GUI
• VISORE
• POSTMAN/CURL
• The API allows the following queries:
• Distinguished Name
• Object Class
• Tree level
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 17
What is MIT? • Distinguished Name query.
• The REST call is performed
on the Dn
• This attribute uniquely
identifies the MO instance
• The query will produce a
single instance.
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 18
What is MIT? • Class object query.
• The REST call is performed to
the name that identifies the
object type.
• The query can produce a
single instance or various
intances as response.
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 19
What is MIT? • Tree query.
• The REST call is performed on
a particular Dn and its children
objects
• The user can retrieve part of
the MIT based on the define
node
• The query will produce
multiple instance of MOs as
response
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 20
API Inspector • ACI RESTful API
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 21
API Inspector
• The Api Inspector allows the users to watch the API calls the GUI
makes in real-time
• The GUI composes every view with API calls to the Apic’s MIT.
• Api inspector exposes each request and response
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 22
API Inspector
• IP Address of APIC
• Filters for the shown calls
• Search by the class attribute or
value or Request/Response
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 24
Visore
• Visore is a visual navigation tool for the MIT.
• This tool exists in both the Apics and every switch.
• To access it to go: https://<NODE IP>/visore.html
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 25
Visore
• Class or Dn o URL
• Used for basic query
• Property *Later versions of ACI will auto-complete the MO class.
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 28
CURL/ iCURL
• CURL or client URL is a tool that allows the transfer of data from or to a
server.
• CURL support multiple protocols including HTTP, HTTPS.
• CURL enables to read (GET) or modify (POST) resources(MOs) in the Apic
API
• GET
curl -i -H "Accept: application/json" -H "Content-Type: application/json" -X GET http://hostname/resource
• POST -i include
curl -X POST -d @filename http://hostname/resource
-H header “Parameter: Value”
-X <REST OPERATION>
-d Data from @file of text
-k Disables SSL Cert inspection
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 29
CURL/ iCURL
• In case of the apic, the authentication method is:
1. Send user/password to Resource /api/aaaLogin
3. Subsequent operations on the REST API can use this token value as a
cookie named APIC-cookie to authenticate future requests.
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 30
CURL/ iCURL
• Need to have a json file with the user/password
cat <<EOF > user.json
{
"aaaUser" : {
"attributes" : {
"name" : "admin",
"pwd" : ”mypassword!"
}
}
}
EOF
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 32
CURL/ iCURL
• You can read the cookie.txt file to check its content
cat cookies.txt
# Netscape HTTP Cookie File
# https://curl.haxx.se/docs/http-cookies.html
# This file was generated by libcurl! Edit at your own risk.
• This cookie is then used to authenticate following requests to the Apic API.
curl -k -i -b cookies.txt \
-H "accept: application/json" -X GET https://APIC_IPADDRESS/resource.json
• The operation should return a 200 HTTP code and the data in json format.
curl -k -i -b cookies.txt \
-H "accept: application/json" -X GET https://IP_ADDRESS/api/mo/uni/tn-common.json
HTTP/1.1 200 OK
Server: Cisco APIC
Content-Type: application/json
{"totalCount":"1","imdata":[{"fvTenant":{"attributes":"DATA"}}]}
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 33
CURL/ iCURL
• iCurl is an utiility build in the ACI code that allows users for an easier use
of the CURL interface.
icurl -X {GET|POST} http://127.0.0.1:7777/resource.json
• GET :
admin@apic1:~> icurl -X GET http://127.0.0.1:7777/api/mo/uni/tn-common.json
{"totalCount":"1","imdata":[{"fvTenant":{"attributes":{"annotation":"","childAction":"","descr":"","dn":"uni/tn-
common","extMngdBy":"","lcOwn":"local","modTs":"2021-01-07T22:19:07.524+00:00","monPolDn":"uni/tn-common/monepg-
default","name":"common","nameAlias":"","ownerKey":"","ownerTag":"","status":"","uid":"0"}}}]}
• POST:
cat << EOF > myTenant.json add “status”:”deleted” to the body in order to delete the object
{"totalCount":"1","imdata":[{"fvTenant":{"attributes":{"dn":"uni/tn-TestTN"}}}]}
EOF
admin@apic1:tmp> icurl -X POST -d @myTenant.json http://127.0.0.1:7777/api/mo/uni/.json
{"totalCount":"0","imdata":[]}
admin@apic1:tmp> icurl -X GET http://127.0.0.1:7777/api/mo/uni/tn-TestTN.json
{"totalCount":"1","imdata":[{"fvTenant":{"attributes":{"annotation":"","childAction":"","descr":"","dn":"uni/tn-
TestTN","extMngdBy":"","lcOwn":"local","modTs":"2021-01-13T20:55:55.729+00:00","monPolDn":"uni/tn-common/monepg-
default","name":"TestTN","nameAlias":"","ownerKey":"","ownerTag":"","status":"","uid":"15374"}}}]}
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 34
CURL/ iCURL
• Both curl and icurl commands accept the same kind of parameters syntax.
• We can use Visore to help us form our query in icurl.
• For example:
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 35
CURL/ iCURL
/api/class/fvAEPg.xml?query-target-filter=and(wcard(fvAEPg.dn,"av"))
• Resource – This can be a class or a specific object by it’s dn
• Format – Type of data structure used, json|xml
• Options – Allowing for advance filter for the query.
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 36
CURL/ iCURL
/api/class/fvAEPg.xml?query-target-filter=and(wcard(fvAEPg.dn,"av"))
/api/class/fvAEPg.xml?query-target-filter=and(wcard(fvAEPg.dn,"av"))
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 39
CURL/ iCURL
• Allows user to define the query for the MO, or it’s children Mos Respond-only elements
target-subtree-class class name including the specified
class
• Enables users to only show results matching certain criteria.
Respond-only elements
query-target-filter filter expressions
matching conditions
• For example, value in certain attributes, or the name of a class
Specifies child object level
rsp-subtree {no | children | full}
included in the response
Expand results: rsp-subtree-class class name
Respond only specified
classes
• This includes filters to include child object, or subtree. Respond only classes
rsp-subtree-filter filter expressions
matching conditions
• Other option is to include the related Health and Statistics MOs. rsp-subtree-include {faults | health :stats :…} Request additional objects
classname.property | {asc Sort the response based
Order results: order-by
| desc} on the property values
query-target-filter=[eq|ne](attribute,value
• The API allows for upto 20 concatenated filter expressions in a
single query.
query-target-filter=[and|or]([eq|ne](attribute,value),[eq|ne](attribute,value),...)
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 41
CURL/ iCURL Operator Description
eq Equal to
ne Not equal to
• The expression needs to have a logic lt Less than
to evaluate. le
ge
Less than or equal to
string values
and Logical AND
or Logical OR
false
Boolean TRUE
Boolean FALSE
enabling API Inspector. anybit TRUE if at least one bit is set
• We can copy/paste operations in the allbits TRUE if all bits are set
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 42
CURL/ iCURL
• In order to test it, we need to enable API inspector
• Then go to the view or tab of interest.
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 43
CURL/ iCURL
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 44
CURL/ iCURL
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 45
CURL/ iCURL
• Using the same logic, we can check the class queried by removing
the filters:
/api/node/mo/comp/prov-VMware/ctrlr-[ACIMxDcP4]-vc.Contr/sw-dvs-213.json?
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 46
POSTMAN • ACI RESTful API
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 47
POSTMAN
• Postman is an API(application programming interface)
development tool which helps to build, test and modify APIs.
• Postman is an API that provides a GUI framework to send REST
Operations to Web Servers.
• Features:
• Support for HTTP requests - GET, POST, PUT, PATCH
• Environment variables for reuse
• Capabilities to convert API code to various languages.
• Multi OS support.
• Download: https://www.postman.com/postman
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 48
POSTMAN
• We can use POSTMAN to connect to the ACI API and
manipulate the MIT like a normal browser.
• As we do in a web browser, the first step is to login.
• A successful login attempt will return a cookie that can be stored in
the HTTP header for the later requests.
• POSTMAN allows the users to save this cookie and share it to your
API queries.
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 49
POSTMAN
• Most of the apics will use
a self-signed certificate
• We need to disable SSL
verification in the settings,
otherwise the request will
fail.
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 50
POSTMAN
• Login to APIC
• In the same manner as
one would do in a web
browser, we need to send
the user and password.
• This is done with a POST
• POSTMAN supports
xml/json
• The apic will respond with
a cookie
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 51
POSTMAN
• For the following queries, we need to confirm the cookie sent by
APIC is part of the environment.
• In the right side of the URL you will see an option to see the Cookies
set.
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 52
POSTMAN
• The
/api/mo/uni.{json|xml} URI
can be used to POST
new configuration.
• The app has a space to
add the HTTP body and
to define the language
• Upon a successful
operation, we expect a
200 status code.
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 53
POSTMAN
• The app allows us to both
simple and complex
queries.
• We have the ability to add
the query filter in the URL
directly, or by adding a pair
of Key,Value in the Query
Params view.
• The Body will have the
information in json/xml
format.
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 54
POSTMAN
• Postman allows the user to save the query to a file.
• To do this, click in Save Response you can name the output for later
reference.
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 55
POSTMAN
• Postman has a functionality called Environments, which allows users to
save certain values to later use.
• To create a new Environment, select New-> Environment
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 56
POSTMAN
• In the Environment, we can add for example the username and
password for the credentials to be used.
• These variables can be then referenced by API Calls
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 57
POSTMAN
• We can then reference the values by putting their name inside double
brackets, {{Variable-Name}}
• For a login attempt, use the name for this variable, this way we can
hide the actual value. This can be used with customer to hide their
password.
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 58
Thank you!
© 2020 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 59