1.
Delivering Exceptional User
Experience with REST and
GraphQL APIs
Rebecca Fitzhugh | Director, Developer Relations @ Rubrik, Inc.

2.
 The Concept of Cloud Data Management
 Designing with REST and GraphQL
 Insights into API Usage

3.
Concept of
Cloud Data Management

4.
 API as a premium
– Our API is only available in the Super Deluxe Platinum Enterprise Premium edition
 API as a side project to address specific large customers
– Customer X requires automation of feature Y, so add a shim
 API for a specific acquisition
– The portfolio contains a few products that came with an API
 API as a bolt-on
– The “YOLO” approach with a bolt-on proxy

5.
 Software Converged
 Infinite Scalability
 API-Driven Architecture
 Instant Data Access
 Cloud Native

6.
Data Center
Protection
Cloud
Protection
Data
Assurance
Disaster
Recovery
Data
Governance
Eliminate tape back-
ups, tighten RPO and
RTO, archive for long
term retention and
orchestrate recovery
of workloads on-
premises
Centralize
orchestration and
automation for in-
cloud backup,
archival and restores
across multiple
clouds
Proactively identify
suspicious and
anomalous activity.
Quickly rollback and
restore service in the
event of a
ransomware attack
Automatically
discover non-
compliant sensitive
data to reduce risk
exposure, costly
audits and regulatory
fines
Leverage cloud as a
DR site in the event
of a failure to ensure
uninterrupted service
and business
continuity

7.
VM
NAS
VM
Global
Management
Ransomware
Recovery
O365
Protection
Cloud App
Protection
Disaster
Recovery
Data
Classification
GraphQL
REST

8.
 Started with REST since GraphQL was
still closed source at Facebook (and
very new)
 Adopted GraphQL for our Polaris SaaS
product.
– Much easier to iterate / develop against.
– Dramatically less requests needed (often
single query).
– Strongly typed model for the win!
https://crystallize.com/comics/rest-vs-graphql

9.
Design Principles with
REST and GraphQL

10.
 Use predictable, resource, and action-oriented URLs
 Use HTTP status codes for handling errors and responses
 Allow sophisticated authentication mechanisms (such as API Keys).
 Support versioning
 Aim to be understood by standard HTTP clients
 Create a maintainable spec that supports all our use cases

11.
 Distributed systems to chat with
each other
 Supply the GUI with an interface

12.
 There were no API versions
 Breaking changes were normal
 Standards for model, params, enums, etc. did not exist
 The product surface area was rapidly expanding

13.
 Things we heard from Engineering:
– The API is just for the product to consume; no one else uses them.
– GraphQL is self-documenting and strongly-typed, so no docs are needed.
– Let’s just make another endpoint for Resource X.

14.
- Engineering, circa 2016

15.
Place major integration points
(parents) at root level of the API
Add child items to each parent
Leverage HTTP methods to
simplify workflows
Ugly: POST to “/add_node” and
“/remove_node/{id}”
Pretty: POST to “/node” and DELETE to
“/node/{id}”
Use Boolean field naming
conventions
Start with ‘has’, ‘is’ or ‘should’ to make it clear that it is a
Boolean field
Examples: ‘hasRootAccess’, ‘isAdmin’ and
‘shouldDoSomething’

16.
Create a consistent and deterministic
experience when dealing with a huge
surface area of integration points: Hypervisors
Cloud
Native
Services
Legacy
Services
File
Servers
Virtual
Appliances

17.
Introduced a version into the path*
Establish a specific version control process
and model
Use “/internal” to develop new endpoints, but
make available to end-users
Use “/v1”, “/v2”, “/vn” to publish stable
endpoints
*not applicable in GraphQL

18.
 No incentives for versioning
 Over 95% of the API resided in
Internal

19.
- me

20.
The rules of versioning
and deprecation
Future deprecation of
endpoints / resources
New or updated
endpoints / resources

21.
There goes the neighborhood

22.
 Dramatic speed improvements for the GUI
 As more objects are added, REST continues to fall behind
 Simple to query all objects and use cursor / pagination
 More flexibility with our returned values
Stress tested load times
95th percentile load times with GraphQL: 3.256 seconds
95th percentile load times with REST: 6.619 seconds

23.
 Added GraphQL to our on-premises
product.
– Reporting
– Dashboards
– Various other components
 Constructed a SaaS platform with
GraphQL as the standard API
– Started from scratch
– Using what we learned
– Lots of tweaking

24.
 Schema tools (Voyager, GraphiQL) for visualization
 Internal construction of new SDKs
 Existing auth methods (e.g. tokens) are valid globally
Base platform will continue with REST and GraphQL
SaaS platform will remain entirely GraphQL
Using GitHub private repos for development

25.
 Schema is in flux
 There are no versions
 Documentation holy wars
 User education

26.
Insights into API Usage

27.
DevOps & Developers
– “Give me API docs, I’ll build
my own integration”
 Python
 Golang
 Ansible
 Terraform
Systems Administrators
– Script common tasks
 PowerShell
 Python
Enterprise Architects
– “Can X integrate with Y?”

28.
 Things we hear from IT Ops:
– There’s no need to learn an API; they are for developers only
– SDKs and Tools are abstraction layers; just focus on that
– The product should do everything and never require API usage.

29.
 Too focused on the technology
 Not enough focus on the hygiene
 Lots of questions from our customers
 General fear of GitHub and coding
More was needed

30.
- Our API Users

31.
Educational Workshops for Operators

32.
 Let use cases drive stack-ranking
 Mimic a near-identical UX
 Educate and enable in parallel
 Invite early-adopters and give them
checklists

33.
Takeaways

34.
 Increased collaboration with engineering and support
 Create incentives to document and polish the API
 Make documentation a top priority
 Educate internal stakeholders on API usage
 Bring (more) operators into the SDK build process
Use cases, UX, testing, feedback

35.
Twitter: @RebeccaFitzhugh
GitHub: rfitzhugh
LinkedIn: /rmfitzhugh

36.
Don’t Backup. Go .