Weitere ähnliche Inhalte Ähnlich wie apidays LIVE New York 2021 - Building Contextualized API Specifications by Boris Vernoff, ADP (20) Kürzlich hochgeladen (20) apidays LIVE New York 2021 - Building Contextualized API Specifications by Boris Vernoff, ADP1. 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
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
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
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
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
35. Copyright © 2021 ADP, Inc.
Thank you
Boris Vernoff
boris.vernoff@adp.com
Linked-In
https://www.linkedin.com/in/boris-vernoff
35