The New Archer REST

API: A Practical
Introduction
James Griffith
RSA

#ArcherSummit

© Copyright 2014 EMC Corporation. All rights reserved. 1

Speaker Background
James Griffith
 Manager In The RSA Archer Quality Team
 3½ Years With RSA, Joined From Commerce
Bancshares N.A.
 Background In Software Development And IT
Consulting
 james.griffith@rsa.com
 linkedin.com/in/jacgriffith

 Manages the RSA Archer Performance And Test Automation Teams

 Subject Matter Expert On The RSA Archer SOAP API
 Oversees Automated Testing Of REST API
 Have Helped Customers Combine REST And SOAP API Integrations

© Copyright 2014 EMC Corporation. All rights reserved. 2

Housekeeping
 Happy To Take At End Of Each Section
 Or Talk To Me Afterwards
 Slides And Code Samples will be available on
the Archer Community After The Summit

#ArcherSummit

© Copyright 2014 EMC Corporation. All rights reserved. 3

Programming Languages

 Demos Today Use C#

– But You Can Use Pretty
Much Any Programming Or
Scripting Language
– The Actual Calls To The
Web Service API Are The
Same, Irrespective Of The
Language
 The API Is Exposed Via
HTTP(S)
 Anything That Can Make An HTTP Call Is
Supported
#ArcherSummit

© Copyright 2014 EMC Corporation. All rights reserved. 4

Today’s Agenda
 Introduction: What Is The Archer REST API?
 Hints About Using The REST API
 Demo: Using The REST API To Upload An
Attachment

#ArcherSummit

© Copyright 2014 EMC Corporation. All rights reserved. 5

What?
Overview Of The REST API

#ArcherSummit

© Copyright 2014 EMC Corporation. All rights reserved. 6

 API Basics - SOAP
 Tried And Tested Technology
 Usually Serializes Data Via XML
 XML Is Pretty Verbose
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<UpdateRolePagePermissions2 xmlns="http://archer-tech.com/webservices/">
<sessionToken>string</sessionToken>
<roleId>int</roleId> XML
<pageId>int</pageId>
<create>boolean</create>
<read>boolean</read>
<update>boolean</update>
<delete>boolean</delete>
</UpdateRolePagePermissions2>
</soap:Body>
</soap:Envelope>

#ArcherSummit

© Copyright 2014 EMC Corporation. All rights reserved. 7

SOAP Is Old News
 No Longer Favored
– XML Is Pretty Verbose
– No Governing Structure – Can’t Tell From A SOAP
Call What Is Being Done
 New Industry Standard Is REST
– Representational
– State
– Transfer
 Basically Means We Get Context Of What Is
Happening From The HTTP Call
#ArcherSummit

© Copyright 2014 EMC Corporation. All rights reserved. 8

HTTP And REST
HTTP Is
 Verb URI The Protocol Underlying The
EffectWeb

– Very Simple Retrieves

GET http://myserver/archer/api/core/application/id=123 information about
– Governs Passage Of Data To/From Server application 123

– Simple List Of Verbs Creates a new

POST http://myserver/archer/api/core/application/
▪ GET application

▪ PUT Updates application

PUT http://myserver/archer/api/core/application/id=123
123
▪ POST
DELETE
▪ DELETE
http://myserver/archer/api/core/application/id=123
Deletes application
123
 In REST These Verbs Govern Actions
 Archer API Currently Better Described As RESTful
#ArcherSummit

© Copyright 2014 EMC Corporation. All rights reserved. 9

What About The SOAP API?
 Existing SOAP API Stays
– Lots Of Existing Deployments Depend On It
– Archer-to-Archer Feeds Depend On It
– Lots Of Automated Tests Cover It
– SOAP API Does Some Things REST API Doesn’t
Do Yet
 Moreover, REST API Roadmap Driven By New
Product Features, Not As Generic Integration
Tool
 In The Far Long Term Expect SOAP To Be
Retired
#ArcherSummit

© Copyright 2014 EMC Corporation. All rights reserved. 10

SOAP Versus REST Today
REST SOAP
http://....../RSAArcher/api/ http://....../RSAArcher/ws

• Log In / Out • Log In / Out

• Add Record • User/Group Admin
• Edit Record • Add Record
• Retrieve Metadata • Edit Record
• Upload Attachment and • Delete Record
Image Files • Search
• Special Methods For • Run Reports
Mobile, RV and Scheduler • Trigger Mail Merge

#ArcherSummit

© Copyright 2014 EMC Corporation. All rights reserved. 11

How?
Calling The REST API

#ArcherSummit

© Copyright 2014 EMC Corporation. All rights reserved. 12

Overview Of The REST API
Append to URL Purpose Notes

Access to login and logout Login method provides session

core/security/method_name
methods token for later actions.

Access to various metadata- Only implemented for GET

core/system/method_name related items, e.g. applications, Must supply a header containing
fields, users session token

Must supply a header containing

core/content/ GET, PUT or POST content
session token

Must supply a header containing

GET or POST attachments and
core/content/attachment session token
image files

Complex methods specific to the Unlikely to be useful for other use

mobile/method_name
Archer Mobile app cases

Methods to support new

Unlikely to be useful for other use
internal/method_name functionality Relationship
cases
Visualization

#ArcherSummit

© Copyright 2014 EMC Corporation. All rights reserved. 13

Overview Of The REST API
 Installed Under Default Folder
– Version 5.4.1 And Above
– Early Version In 5.4 Is Installed Manually
core/content/attachment
core/security/logout
core/content/205778
https://myserver/RSAArcher/api/ core/security/login
core/system/application/123

– Additional Information Passed In Via

▪ HTTP Headers
▪ JSON and XML

#ArcherSummit

© Copyright 2014 EMC Corporation. All rights reserved. 14

What A Call Looks Like
For all calls
HTTP Verb except login
(GET , POST etc)
HTTP Request

URL

Accept: application/json,text/html,
application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Authorization: Archer session-id="*************"
HTTP Content-Type: application/json
Request Header X-Http-Method-Override: GET

Body JSON or XML

#ArcherSummit

© Copyright 2014 EMC Corporation. All rights reserved. 15

Login Demo

#ArcherSummit

© Copyright 2014 EMC Corporation. All rights reserved. 16

JSON
{
{ Field IDs
"Links":[]
"Links":[]
,"RequestedObject":
,"RequestedObject":
{"Id":123427
{"SessionToken":"8D324BB85A7AEE9D66566242B84BA31F"
,"LevelId":17
,"InstanceName":"Archer1"
,"SequentialId":1
,"UserId":191
,"FieldContents":
,"ContextType":0 {"110":
Data in
,"UserConfig": {"Type":6 the fields
,"FieldId":110
{"TimeZoneId":"India Standard Time"
,"UpdateInformation":
,"TimeZoneIdSource":1
{"CreateDate":null
,"LocaleId":"en-CA" ,"UpdateDate":null
,"LocaleIdSource":1 ,"CreateLogin":null
,"LanguageId":1 ,"UpdateLogin":null}
,"LanguageIdSource":1
}
,"4765":
,"PlatformLanguageId":1
{"Type":8
,"PlatformLanguageIdSource":0}
,"Value":{"UserList":
,"Translate":false} [
,"IsSuccessful":true {"Id":204
,"ValidationMessages":[] ,"HasRead":true
} ,"HasUpdate":true
,"HasDelete":false
}
] #ArcherSummit

© Copyright 2014 EMC Corporation. All rights reserved. 17

FieldContents In Content JSON
Text Field Numeric Field Values List Cross Reference

FieldContents FieldContents FieldContents FieldContents

{ { { {
"2432" : "7848" : "3202" : "46918" :
{ { { {
"Type":1 "Type":2 "Type":4, "Type":9
,"Value":“Text” ,"Value":52 "Value": ,"Value":
,"FieldId":2432 ,"FieldId":7848 { [
} } "ValuesListIds" : {
… … [2405,2406,2407], "ContentId": 123427
"OtherText":"Blue" ,"LevelId":17
} }
, "FieldId":3202 ]
} ,"FieldId":46918}
… …

Where 2405 = Yellow, Note the use of the array

2406 = Red, 2407 = [] which contains {}
Green etc structures

#ArcherSummit

© Copyright 2014 EMC Corporation. All rights reserved. 18

Further Tips
 Use Of ODATA To Narrow Request Results
– ODATA Queries Passed In Through Request Body
– Only Retrieve Certain Properties
{"Value":"?$select=Alias,IsSpellCheckEnabled"}
– Order By A Property
{"Value":"?$orderby=IsNotification"}
– Limit Number Of Records
{"Value":"?$top=5"}
– A Few Other Options, Listed In The Help.
{"Value":"?$filter=Name eq 'Test Application'"}

 Dependency On Field IDs

– Cannot Substitute GUIDs
– Write Custom Code To Manage DEV/TEST/PROD
#ArcherSummit

© Copyright 2014 EMC Corporation. All rights reserved. 19

Summary
 Lots Of Information
– Limited Code Samples For This Talk
– See Also Improved 5.5 Version Of API Guide
 Nothing Beats Practice Though, And There
Are Tools That Help
 Recommendations: Other companies’ products,
– Telerik Fiddler so this is a personal
recommendation
– SmartBear SoapUI
 Tool Shows Data To And From The Server
(It Was Used In The Demo)
#ArcherSummit

© Copyright 2014 EMC Corporation. All rights reserved. 20

In-Depth
Uploading To Attachment And
Image Fields Via The REST API

#ArcherSummit

© Copyright 2014 EMC Corporation. All rights reserved. 21

Something SOAP Can’t Do
 Attachment Or Image Field Population
 2 Step Process
– Pass File To Repository
– Tie File To Content Record

File POST /api/core/attachment

Encode
JSON containing file ID

SOAP or REST call with file ID

101010110
101100101
111001010 Content ID
#ArcherSummit

© Copyright 2014 EMC Corporation. All rights reserved. 22

Attachment Upload Demo

#ArcherSummit

© Copyright 2014 EMC Corporation. All rights reserved. 23

Taking It Home
Comments On How To Apply This
Back In The Real World

#ArcherSummit

© Copyright 2014 EMC Corporation. All rights reserved. 24

Set Yourself A Goal
 Do One Thing Next Week To Take Advantage
Of This Information!
– One API Call Against Your Application Next Week
▪ One Of My Code Samples, Updated
▪ Roll Your Own
– Engage Your IT Or Development Resources
▪ Show Them These Slides And Code Samples
▪ Challenge Them To Use The API

#ArcherSummit

© Copyright 2014 EMC Corporation. All rights reserved. 25

Thank you.

#ArcherSummit