Smarts EDAA Tutorial

1 Copyright 2014 EMC Corporation. All rights reserved. 2014 Smarts/SAS User Group Meeting-Dallas Not for Redistribution

Smarts EDAA Tutorial


Representational State Transfer (REST)

REST (REpresentational State Transfer) is a simple stateless architecture that generally runs over HTTP.

The REST style emphasizes that interactions between clients and services is enhanced by having a limited number of operations.

Flexibility is provided by assigning resources their own unique universal resource indicators (URIs).

Because each operation has a specific meaning (GET, POST, PUT and DELETE), REST avoids ambiguity.


REST APIs are tricky

How to use REST predictably for my product? What is the right granularity of API? How do I make this simple for developers? How do I secure this API? How do I handle transactions? How do I advertise and document this API? ...


EMCs approach

Define a standard, consistent approach to APIs allowing

Easier customizability of our products Easier integration amongst our products Easier integration between our products and other IT

Infrastructure management products used by our customers

Use REST and associated best practices around REST


EDAA What is it?

EDAA EMC Data Access API

EDAA is a style of REST API design EDAA says lets all paint like Van Gogh: - Similar style of REST across products


EDAA is available for

SAS Smarts Domain Managers, (SAM, IP, ESM, etc.) NCM

Other ASD Products: ViPR W4N Powerpath UIM


EDAA is Model Independent

EDAA Style

+

Resource Model

= REST API

EDAA is model independent: -we apply EDAA to multiple products -each with its own resource model


Smarts Sample Model THIS IS A VASTLY SIMPLIFIED MODEL, FOR EDUCATIONAL USE ONLY


EDAA Basics

Every EDAA is made up of two base categories.

Types Shows you all the types (classes/resources) available on

a given model. Shows you every required or potential attribute. Shows you every potential relationship and action.

Instances Shows you all instances (objects) currently existing in a

given model. Shows you all current attributes. Shows you every current relationship/action.


http://myserver.com/smarts-edaa/msa/SAM/types?pretty=true

Your web server: http://myserver.com/

Plus the Smarts EDAA webapp: /smarts-edaa/msa/

Plus your Smarts Domain name: SAM/

Plus types to show class information: /types

Plus any combination of parameters: ?pretty=true (for human readable feeds)

Note this parameter is assumed for all of the following use cases.


Use Case 1 Get me all types GET /types (ex. http://server/smarts-edaa/msa/SAM/types)

Atom meta data.

Each type enclosed in entry tags.

Name and URL to a specific type.

Mandatory & optional attributes and their

descriptions.


Use Case 1 Use of Atom Syndication Format Atom Syndication Format: RFC 4287 Collection is modeled as an atom:feed Each item in the collection is an atom:entry Resource representations contained in atom:content

atom:link used to reference collection metadata, and other things

Shortcomings: Some amount of additional bloat Some tags required by atom provide no value in

this context


Use Case 2 Get me a Router type GET /types/Router (Use Case 1 + /Router)

Only a single entry.


Use Case 3 List all Routers GET /types/Routers/instances (Use Case 3 + /instances) Total number

of entries.

Attributes of a Router instance.

Action and relationship URLs for a Router instance.

Name & URL of a Router instance.


Use Case 4 List a specific Router GET /instances/Router::lwqvp250.lss.emc.com

Response has only one entry.

This URL would be found in a atom:link

somewhere (HATEOS)


Use Case 3 - Use of HATEOAS HATEOAS:

Hypermedia as the Engine of Application State

Basically: Use links to indicate what the client can do next

Use of links: Usual Atom stuff (self, next, etc) mainly collection metadata Pagination Individual resource metadata Type information Relationships Actions

Shortcomings: Not many tools exploit HATEAOS Most client apps bake in URI patterns brittle coupling


Use Case 5 ConnectedVia of Router GET instances URL + /relationships/ConnectedVia

IP Network Name and URL.

Number of ConnectedVia entries.

IP Network Attributes.


Use Case 6 Too many results (entries) GET instances URL + /relationships/ConnectedVia

Over 100 results.

Usual Atom meta data.

EDAA only shows 100 entries per page.

Pagination links appear for first, last, next, previous and self.


Pagination

Use of RFC5005 atom pagination and archiving Links to next page of the collection, prev, etc. Use of URI parameters to specify page size and page

index

UC-3 also discusses type hierarchies and collections Can use the per_page parameter to

increase/decrease the number of entries per page.


Use Case 7 JSON! GET instances?alt=json

Same entry structure.

JSON feed & meta data.


XML vs. JSON Both XML and JSON are supported serialization styles

Can also support CSV, others, but not specified

Both XML and JSON have their uses JSON becoming more popular as more and more

clients are JavaScript based

Client specifies serialization type: As query parameter Or content negotiation using Accept: headers

JSON format has all the EDAA features (paging, etc.) equivalent to XML in EDAA


Use Case 8 Create a new Router POST types/Router/instances

POST to a collection is a standard REST pattern of creating new resources

Where the body of the POST contains a representation of the resource to be created


Use Case 9 Update a Router PUT types/Router/instances

PUT to a resource is the way to make changes to that resources property

Where the body contains THE ENTIRE representation of Router::SomeRouter with property changes

A consumer can tell if a resource can be modified, if it sees


Use Case 10 Delete a Router DELETE /instances/Router::OldRouter

DELETE to a resource is the way to remove that resource from the system (delete)

When a resource is deleted, it cannot be retrieved by GET or changed by PUT/POST/DELETE

Leave the body of the DELETE empty.

A consumer can tell if a resource can be deleted, if it sees

The edit link has the href to which PUT/DELETE etc. operations can be sent


Create/Update/Delete Create

POST new resource representation to a collection (this is also how resources are added to the

collection) Update

PUT Patch (sometimes supported)

Delete Delete

Standard approach to REST Look for atom:link with @rel=edit to determine if the resource is modifiable


Use Case 11 Schedule Maintenance

Actions are represented as atom:link elements within a resources representation

POST /instances/Router::oldRouter/action/scheduleMaintenance

The action atom:link might not always appear - maybe the user is not authorized to perform the action - maybe the resource is not in the right state for that action to be meaningful


Use Case 12 Limit returned fields GET /types/Routers/instances?fields=SystemName|Name

Partial representation returned with just a subset of the data.

Separate multiple fields with a pipe.


Use Case 13 Sort my results GET /types/Routers/instances?orderby=Name DESC

Entries are sorted by Name, ascending.


Use Case 13 Filter my results GET /types/Routers/instances?filter=Vendor eq CISCO

Only entries that match the filter will show up in the feed.


Use Case 14 Expand my results GET /types/Routers/instances?expand=ConnectedVia

ConnectedVia feed appears in each instance entry.


Response control through query parms

Partial representations ?fields=

Server-side sorting of collections ?orderby=

Filtering collections into specific subsets ?filter=

Paging ?per_page=100&page=5

These parameters can be combined


?filter expressions Level Operations 1 expressions in parentheses 2 'eq' , 'ne' , 'gt' , 'ge' , 'lt' , 'le', 'in' , 'lk' 3 NOT 4 AND 5 OR

Examples: GET /types/T/instances?filter=p1 eq "a" AND p2 eq "b" AND p3 eq 8 OR p3 eq 9 GET /types/T/instances?filter=(p1 eq "a" AND p2 eq "b" AND p3 eq 8) OR p3 eq 9 GET /types/T/instances?filter=p1 eq "a" AND p2 eq "b" AND (p3 eq 8 OR p3 eq 9)


Smarts EDAA Feature Support Matrix Feature 9.2 9.3

Atom Yes Yes

HATEOAS Yes Yes

Pagination Yes Yes

Types Yes Yes

JSON No Yes

Create (POST) Yes Yes

Update (PUT) No Yes

Delete No Yes

EDAA Feature 9.2 9.3

?orderby No Yes

?filter No Yes

?fields No Yes

?expand No Yes


Smarts EDAA Configuration (9.2)


Smarts EDAA - Configuration

Can be configured in two ways since 9.2: Companion UI (CUI) Smarts SAM Console

Required Information: Domain Manager Name Broker location and port Domain Manager Username & Password An alias for the Domain Managers MSA


Smarts EDAA Configuration - CUI

You can add Domain Managers to the CUI Administration Data Sources GUI.

You need to add in the required information for each EDAA you want to configure.

Add non-SAM servers via Other EMC Smarts Product


Smarts EDAA Configuration - CUI Continued

Once created, the details screen will show you the information you entered as well as the base URI for the EDAA

e.g. https:///msa20-dmt/msa/


Smarts EDAA Configuration - Console

Install the SAM Console. Install JRE 7+. Modify runcmd_env.sh and add:

SM_JAVA=/jre/bin;/jre/bin/client SM_JAVAHOME=/jre

Copy msa20-dmt-*.war from: BASEDIR/tomcat/webapps/msa to BASEDIR/tomcat/webapps Rename msa20-dmt-*.war to msa20-dmt.war

Start tomcat: BASEDIR/bin/sm_tomcat start


Smarts EDAA Configuration - Console Continued

BASEDIR/tomcat/webapps/msa20-dmt will be created.

Stop tomcat: BASEDIR/bin/sm_tomcat stop

Modify BASEDIR/tomcat/webapps/msa20-dmt/WEB-INF/classes/msa-sources.xml to add domains you want to run EDAAs for.

Create a new bean for each domain you wish to run an EDAA for.

Set ModelName to ip. Example on next slide.




Each EDAA can be found at: http://:/msa20-

dmt/msa/



Note: Smarts DM EDAA from the SAM Console does not have any

authentication enabled.


Smarts EDAA Example 9.2 Calls /msa20-dmt/msa/AM/types

Show me all available types on this AM server.

/msa20-dmt/msa/AM/instances Show me all available instances on this AM server.

/msa20-dmt/msa/AM/types/Router Show me the type information for Routers.

/msa20-dmt/msa/AM/types/Router/instances Show me all instances of type Router.

/msa20-dmt/msa/AM/instances/Router:: Show me a specific Router.

/msa20-dmt/msa/AM/instances/Router::/relationships/ConnectedVia

Show me the ConnectedVia relationship of a specific Router.

/msa20-dmt/msa/AM/types/Router/instances?per_page=200 Show me all instances of type Router, 200 at a time.


Smarts EDAA Configuration (9.3)


Smarts EDAA 9.3 Configuration

Still under development. Note it will be much easier than in 9.2.

No CUI. No upgrading tomcat/jre. Packaged with SAM server. Automatic configuration for SAM servers.

(Those used by the UI)


Network Configuration Manager (NCM) EDAA


NCM - Configuration The NCM EDAA lives at:

//ncmmsa/webapps/ncm-msa/

To run, you need to first edit a few configuration files:

//ncmmsa/webapps/ncm-msa/WEB-INF/web.xml_CAS

Add in the location of your CAS (CUI) servers. //ncmmsa/webapps/ncm-msa/WEB-

INF/classes/ncm-resources.xml Add your NCM server and username/password

Start the tomcat server: //ncmmsa/bin/startup.sh


NCM - Available Features in 9.2 1. Atom feed 2. Hateoas (links to

other things) 3. Pagination 4. Type information at

runtime 5. XML and JSON 6. Create/update/delete

resources 7. eTag

8. Hybrid RPC model

9. Long running operations

10.Narrowing the resource representation (?fields)

11.Server side sorting (?orderby)

12.Server side filtering (?filter)

13.Other topics


NCM - Whats coming in 9.3 1. Atom feed 2. Hateoas (links to

other things) 3. Pagination 4. Type information at

runtime 5. XML and JSON 6. Create/update/delete

resources 7. eTag

8. Hybrid RPC model

9. Long running operations

10.Narrowing the resource representation (?fields)

11.Server side sorting (?orderby)

12.Server side filtering (?filter)

13.Other topics


NCM Example 9.2 Calls /ncm-msa/msa/ncm/types/Device/instances

Show me all devices on this NCM instance, (With default paging of 20).

/ncm-msa/msa/ncm/types/ConfigFile/instances Show me all configuration files.

/ncm-msa/msa/ncm/types/Device/instances/103040/relationships/ConfigFile Show me all configurations files for a particular device.


Browsers & Atom


Internet Explorer

IE8+, by default, formats Atom feeds. This makes it easier if you are following relationships and action links. Right-click and view source to see the raw (unformatted) feed.

Defaults to notepad, but you can change it to your favorite text editor.


Firefox

Firefox, by default, formats Atom feeds. Right-click and view source to see the raw (formatted) feed.


Chrome

Chrome, by default, shows raw (formatted) feeds. Extensions, (like XV XML Viewer), can be installed to turn

feed URIs into hyperlinks.


Follow along lab


Locate your EDAAs

Login to your vLab instance. Open Firefox and go to your CUI server address.

E.g. https://lglos218.lss.emc.com

Log in using appadmin/Changeme1!. Click on Manage Data Sources. Select EMC Smarts SAM Presentation Server. Record Base URI.

E.g. https://lglos218.lss.emc.com/msa20-dmt/msa/samp


GET (DMT)

Get SAM EDAA types: https://lglos218.lss.emc.com/msa20-dmt/msa/samp/types

Get SAM EDAA instances: https://lglos218.lss.emc.com/msa20-dmt/msa/samp/instances

Get SAM EDAA router instances: https://lglos218.lss.emc.com/msa20-dmt/msa/samp/types/Router/instances

Get a SAM EDAA router instance: https://lglos218.lss.emc.com/msa20-dmt/msa/samp/instances/Router/

Get a SAM EDAA router instance relationship: https://lglos218.lss.emc.com/msa20-

dmt/msa/samp/instances/Router//relationships/ConnectedVia


GET (Alert Service)

Get Alert Service EDAA instances: https://lglos218.lss.emc.com/srm/alert/msa/types/Alert/instances

Get Alert Service EDAA with sort: https://lglos218.lss.emc.com/srm/alert/msa/types/Alert/instances?orderby=severity

%20DESC

Get Alert Service EDAA with filter: https://lglos218.lss.emc.com/srm/alert/msa/types/Alert/instances?filter=severity%2

0eq%201

Get Alert Service EDAA with filter and increase page size:

https://lglos218.lss.emc.com/srm/alert/msa/types/Alert/instances?filter=severity%20eq%201&per_page=200


POST Schedule Maintenance via SAM EDAA

From Firefox, search for Firefox poster. Install Firefox plug-in, (requires browser restart).

Launch Poster From the SAM EDAA locate an object to post to.

E.g. https://lglos218.lss.emc.com/msa20-dmt/msa/samp/instances/Router::10.9.29.124/action/scheduleMaintenance

Create the Maintenance argument to post:

2013-10-3T17:00-0500 2012-10-4T19:00-0500 admin INCHARGE-SA Move to a new rack

Add these to Poster, w/ CAS username & password and POST.


Perl Useful Libraries

REST::Client: http://search.cpan.org/~mcrawfor/REST-Client-

171/lib/REST/Client.pm

Libwww-perl: http://search.cpan.org/dist/libwww-perl/


Python Useful Libraries

REST kit: https://pypi.python.org/pypi/siesta

Requests: https://pypi.python.org/pypi/requests

Siesta: https://pypi.python.org/pypi/siesta


Java Useful Libraries

Jersey https://jersey.java.net/

Camel: http://camel.apache.org/

Smarts EDAA TutorialRepresentational State Transfer (REST)REST APIs are trickyEMCs approachEDAA What is it?EDAA is available forEDAA is Model IndependentSmarts Sample ModelEDAA Basicshttp://myserver.com/smarts-edaa/msa/SAM/types?pretty=trueUse Case 1 Get me all typesUse Case 1 Use of Atom Syndication FormatUse Case 2 Get me a Router typeUse Case 3 List all RoutersUse Case 4 List a specific RouterUse Case 3 - Use of HATEOASUse Case 5 ConnectedVia of RouterUse Case 6 Too many results (entries)PaginationUse Case 7 JSON!XML vs. JSONUse Case 8 Create a new RouterUse Case 9 Update a RouterUse Case 10 Delete a RouterCreate/Update/DeleteUse Case 11 Schedule MaintenanceUse Case 12 Limit returned fieldsUse Case 13 Sort my resultsUse Case 13 Filter my resultsUse Case 14 Expand my resultsResponse control through query parms?filter expressionsSmarts EDAA Feature Support MatrixSmarts EDAA Configuration (9.2)Smarts EDAA - ConfigurationSmarts EDAA Configuration - CUISmarts EDAA Configuration - CUISmarts EDAA Configuration - ConsoleSmarts EDAA Configuration - ConsoleSmarts EDAA Configuration - ConsoleSmarts EDAA Configuration - ConsoleSmarts EDAA Configuration - ConsoleSmarts EDAA Example 9.2 CallsSmarts EDAA Configuration (9.3)Smarts EDAA 9.3 ConfigurationNetwork Configuration Manager (NCM) EDAANCM - ConfigurationNCM - Available Features in 9.2NCM - Whats coming in 9.3NCM Example 9.2 CallsBrowsers & AtomInternet ExplorerFirefoxChromeFollow along labLocate your EDAAsGET (DMT)GET (Alert Service)POSTPerl Useful LibrariesPython Useful LibrariesJava Useful LibrariesSlide Number 65

Smarts EDAA Tutorial

Documents

Transcript of Smarts EDAA Tutorial