The document discusses how ADP provides customized API specifications tailored to various contexts, addressing the diverse needs of its clients and partners. It highlights the importance of context-aware documentation, user roles, and the ability to define specifications that vary based on operational requirements. Ultimately, ADP aims to maintain a consistent canonical version while allowing for multiple contextualized variations to support different consumers.

1. Copyright © 2021 ADP, Inc.
Copyright © 2021 ADP, Inc.
Building Contextualized API Specs
One Size Does Not Fit All
Boris Vernoff
Boris Vernoff

2. Copyright © 2021 ADP, Inc.
About ADP
• Over 740,000
clients worldwide
• 140+ countries
• More than 35
million users
• 5 million logins a
day
• Wide breadth of
HCM and payroll
solutions
• Best HCM service
and BPO offerings
2

3. Copyright © 2021 ADP, Inc.
ADP’s Strength is Data
3
APIs
HR Payroll Talent
Time Benefits
Staffing Tax
Money
Movement

4. Copyright © 2021 ADP, Inc.
“…every company is a software company; every
company is a digital organization…”
Satya Nadella, Microsoft CEO
4
Quote of the Day

5. Copyright © 2021 ADP, Inc.
Service Company
5

6. Copyright © 2021 ADP, Inc.
Software Company
6

7. Copyright © 2021 ADP, Inc.
ADP as a Software Company
• Grew through acquisitions
• Includes variety of products - different platforms and technologies
• Difficult to integrate across multiple products
API Everything
7
Data Synchronization ADP Goes Mobile Marketplace Digital Transformation

8. Copyright © 2021 ADP, Inc.
Service Expansion
8
HR
Payroll
Talent
Benefits
Staffing
Money
Movement
Payroll
Payroll
HR
HR
Benefits
Benefits

9. Copyright © 2021 ADP, Inc.
Success of API Program
Partners
Developers
Clients
Product
Owners

10. Copyright © 2021 ADP, Inc.
API Specification - Does One Size Fit All?

11. Copyright © 2021 ADP, Inc.
HCM Challenge – Context Varies
11
• Applicability of data may vary
• Constraints may vary
• Valid values may vary
• Relevant operations may vary
Standard
Object
Industry
Constraints
Client
Constraints
Regional
Context

12. Copyright © 2021 ADP, Inc.
Dimensions of Context
• Provider
• Various levels / flavors of service
• Geo-Political
• Government rules & regulations
• Industry Specific
• Different fields / industries can have different accents
• Consumer
• Internal vs. external
• Partner vs. customer
• Developer vs. product owner
12

13. Copyright © 2021 ADP, Inc.
API Specification Components
13
JSON
Request / Response / Event Model
Usage Examples / Scenarios
URIs / Operations
Headers / Parameters
Response Codes
Descriptions
Object Model / Sequence

14. Copyright © 2021 ADP, Inc.
Solution - Requirements
14
• Context-aware Developer’s portal
• Partner – choice of contexts
• Consumer – subscription-based context
• Context-specific API documentation
• Contextualized schemas w/ tailored examples
• Selective operation support
• Customized business rules
• API Registry
• Data-driven API specification generation
• User access / entitlements management
• Infrastructure integrated

15. Copyright © 2021 ADP, Inc.
API Portal Access Diagram
15
User authenticated
to API Portal
Partner sets
context
API Provider
(feature + context)
identified
Relevant
contextualized
specs presented
“Editor
vs. “Viewer”
access granted
User roles

16. Copyright © 2021 ADP, Inc.
User Roles and Entitlements
16
• Consumer (Client Co)
• Read contextualized specs based on the context subscribed
• Consumer (Partner Co)
• Choose context based on the partner agreement
• Read contextualized specs using any context allowed
• API Designer (Provider)
• Read & clone canonical (templates) and contextualized specs
• Create new contexts / contextualized specs (own provider)
• API Architect (COE)
• Read & clone canonical and contextualized specs
• Create new contexts / contextualized specs
• Define new / modify existing canonical spec templates

17. Copyright © 2021 ADP, Inc.
User Roles (Cont’d)
17
• Administrator
• Manage users and entitlements
• Manage and maintain CI/CD pipelines

18. Copyright © 2021 ADP, Inc.
Specification Contextualization
18
Let the Fun Begin

19. Copyright © 2021 ADP, Inc.
Context Definition
19
Product /
Provider
Region
Industry

20. Copyright © 2021 ADP, Inc.
Context Selection
20
Edit titles, descriptions,
upload examples, make
schema adjustments

21. Copyright © 2021 ADP, Inc.
Context Selection Dashboard
21
Canonical /
templates
Provider Provider /
Region
Provider Provider /
Region
Provider
Provider

22. Copyright © 2021 ADP, Inc.
API Contextualization
22
• Choose operations supported
• Update operation descriptions / summaries
• Choose supported headers / query parameters
• Modify query parameter obligation / exposure
• Define usage scenarios
• Associate request and response, provide descriptions
• Upload scenario specific payload examples

23. Copyright © 2021 ADP, Inc.
API Contextualization - Operations
23
Available operations
as per canonical
definition
Selected operations
for a given context

24. Copyright © 2021 ADP, Inc.
API Contextualization - Descriptions
24
Main title
Main
description
Section title
Section
description
Operation title
Operation
description

25. Copyright © 2021 ADP, Inc.
Usage Scenarios
25
Custom scenario
description

26. Copyright © 2021 ADP, Inc.
Usage Scenarios – Custom Response Examples
26
Response
Specific
example

27. Copyright © 2021 ADP, Inc.
API Usage Scenarios - Overview
27
Defined
scenarios
Applicable
responses
Response
payload
example
Download
current or paste
new content

28. Copyright © 2021 ADP, Inc.
API Contextualization - Schema
28
Canonical
schema
Attribute
selection
Context
selection
Descriptions,
obligation, ranges,
enumerations, etc.
Array
attributes
Date
attributes
Numeric
attributes
Save
schema

29. Copyright © 2021 ADP, Inc.
Access Entitlement Management
29
Allowed
Available

30. Copyright © 2021 ADP, Inc.
Access Entitlement Management (cont’d)
30

31. Copyright © 2021 ADP, Inc.
Contextualized API Specs - Documentation
31
Supported
operations
Product /
Context
Scenario(s)
Custom
summary

32. Copyright © 2021 ADP, Inc.
Contextualized API Specs - Documentation (cont’d)
32
Supported
user roles
Postman
collections

33. Copyright © 2021 ADP, Inc.
Summary
• The same API specification can vary for different consumers (usage
context driven)
• API documentation portal supports role-based access and API
documentation is tailored to the specific consumer
• API provider can define multiple “flavors” of the specification based on
various usage contexts
• All variations must be a subset of the canonical version - consistency
is the key
One Size Does Not Fit All
33

34. Copyright © 2021 ADP, Inc.
Questions
34

35. Copyright © 2021 ADP, Inc.
Thank you
Boris Vernoff
boris.vernoff@adp.com
Linked-In
https://www.linkedin.com/in/boris-vernoff
35