Delivering Exceptional User Experience with REST and GraphQL APIs Rebecca Fitzhugh, Director, Developer Relations at Rubrik

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

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

8. 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

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

10.  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

11. Design Principles with
REST and GraphQL

12.  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

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

14.  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

15.  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.

16. - Engineering, circa 2016

17. 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’

18. 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

19. 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

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

21. - me

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

23. There goes the neighborhood

24.  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

25.  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

26.  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

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

28. Insights into API Usage

29. 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?”

30.  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.

31.  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

34. - Our API Users

35. Educational Workshops for Operators

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

38. Takeaways

39.  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

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

41. Don’t Backup. Go .