Video and slides synchronized, mp3 and slide download available at URL http://bit.ly/2xCHu90. Aditya Modi and Karthik Ramgopal explore LinkedIn’s original ideas behind API modeling, the challenges they’ve faced, and how they are evolving their modeling strategy over time based on their learnings. They present a use case study of building the templated API behind LinkedIn’s new in-app notification experience. Filmed at qconnewyork.com. Karthik Ramgopal is a Senior Staff engineer in the application infrastructure group, and leads the mobile infrastructure team at LinkedIn. Aditya Modi is a Staff Software Engineer in the Application Infrastructure team. He leads the infrastructure development for the front-end API server, which powers the LinkedIn app on iOS, Android and Web.

1. Front-End APIs
Powering Fast-Paced Product Iterations

2. InfoQ.com: News & Community Site
• 750,000 unique visitors/month
• Published in 4 languages (English, Chinese, Japanese and Brazilian
Portuguese)
• Post content from our QCon conferences
• News 15-20 / week
• Articles 3-4 / week
• Presentations (videos) 12-15 / week
• Interviews 2-3 / week
• Books 1 / month
Watch the video with slide
synchronization on InfoQ.com!
https://www.infoq.com/presentations/
linkedin-api-modeling

3. Presented at QCon New York
www.qconnewyork.com
Purpose of QCon
- to empower software development by facilitating the spread of
knowledge and innovation
Strategy
- practitioner-driven conference designed for YOU: influencers of
change and innovation in your teams
- speakers and topics driving the evolution and innovation
- connecting and catalyzing the influencers and innovators
Highlights
- attended by more than 12,000 delegates since 2007
- held in 9 cities worldwide

4. Speakers
​Jeff Weiner
​Chief Executive Officer
​Aditya Modi
​Staff Software Engineer
​Karthik Ramgopal
​Sr Staff Software Engineer

5. Overview
History and evolution of frontend APIs at LinkedIn
Our API structure today
Learnings and results
Sneak peek at the future

6. 2 Years Ago

7. Mobile v/s Desktop
Feed on mobile Feed on desktopFeed on iPad

8. Client - Server setup
mobile-frontend-API tablet-frontend-API homepage-frontend-API profile-frontend-API
Android iOS Tablet homepage-desktop-web profile-desktop-web

9. • Huge API surface and diversity
• No IDL/schema backing API
• Slow iteration speed
Problems?

10. Today

11. Mobile v/s Desktop
Feed on mobile Feed on desktopFeed on iPad

12. Client - Server setup
flagship-frontend-API
flagship-android flagship-iOS flagship-desktop-webflagship-mobile-web
Rest + JSON over HTTP2
Mid-tier . . . . Mid-tier

13. • > 120k QPS
• ~425 developers
• ~30 commits per day
Scale

14. • Automated continuous release
• commit to production in < 3 hours
• 3 deployments a day
3x3 Deployment

15. Modeling

16. • Backed by Strongly Typed Schemas
• Backward-compatible evolution
• No endpoint versioning
Principles

17. {
"type": "record",
"name": "TestRecord",
"namespace": "com.linkedin.test",
"doc": "Test",
"fields": [
{
"name": "id",
"type": "String",
"doc": "ID"
},
{
"name": "name",
"type": "String",
"doc": "Name",
“optional”: true
},
]
}
@interface TestRecord : NSObject
@property(nonnull, copy) NSString *id;
@property(nullable, copy) NSString *name;
@end
class TestRecord {
@NonNull public final String id;
@Nullable public final String name;
}
export default DS.Model.extend({
id: DS.attr(‘string’),
name: DS.attr(‘string’)
});
Schema definition
iOS
Android
Web

18. Entity Modeling
• Return - Collection<Card>

19. Composite screens
● Two top level resources
■ Invitations
■ PYMK (People You May Know)
● 1 network call to fetch both resources
■ Infrastructure level aggregation support

20. • Easy to model
• Decouple API from UI
• Client side consistency
Advantages

21. Client side consistency

22. Client side consistency
• Why ?
○ Good UX
○ Optimistic writes

23. Client side consistency
Can you do this auto-magically?

24. Client side consistency
Payload Cache

25. Client side consistency
Payload Cache

26. Client side consistency
Cache Payload

27. Everything is awesome, right?

28. Takes a long time to ship a feature
API Server
1.5 weeks
iOS
2 weeks
Android
2 weeks
Web
2 weeks
Total time
3.5 weeks=+
Use case: Introduce a new kind of notification

29. • Create new models for every feature
• Write code on each client platform
• Wait for native app release/adoption
Why so long?

30. Challenge
Cut this down to 1 day!

31. • Quickly build and release notifications
• Increase user engagement
• Sweet and sticky, just like honey!
Project Honeycomb

32. • New notifications WITHOUT app updates
• Client side consistency
• Stellar runtime performance
Beyond iteration speed...

33. • Model based on how the UI view looks
• Similar views grouped into 1 template
• More UI specific logic on API server
View Template API

34. Share notification
Share Template
● PrimaryImage: URL?
● Title: AttributedString
● Timestamp: Long
● ShareImage: URL?
● ShareTitle: String
● LikeCount: Long? (Default: 0)
● CommentCount: Long? (Default: 0)

35. Now let’s look at a slightly different notification
Modify Share Template
● PrimaryImage: URL?
● Title: AttributedString
● Timestamp: Long
● ShareImage: URL?
● ShareTitle: String AttributedString
● ShareSubtitle: AttributedString?
● LikeCount: Long? (Default: 0)
● CommentCount: Long? (Default: 0)

36. How about something radically different?
Work Anniversary Template
● PrimaryImage: URL?
● Title: AttributedString
● Timestamp: Long

37. Something slightly different again?
Work Anniversary/New Position Template
● PrimaryImage: URL?
● Title: AttributedString
● Timestamp: Long
● BodyText: AttributedString?

38. How do we return a heterogeneous list?
• Use Rest.li paginated collections. Differentiate between items using a Union.
• JSON payload structure:
{
“elements” : [
{“Share”: {“Title”: “Sarah Clatterbuck shared a…”, ...}},
{“Anniversary”: {“Title”: “Congratulate Nitish Jha…”, ...}},
....
],
“paging”: { “start” : 0, “count”: 10, “paginationToken”: “xydsad”}
}

39. Minor payload optimization
• Embed the type into the payload to reduce nesting.
• JSON payload structure:
{
“elements” : [
{“Type”: “Share”, “Title”: “Sarah Clatterbuck shared a…”, ...},
{“Type”: “Anniversary”, “Title”: “Congratulate Nitish Jha…”, ...},
....
],
“paging”: { “start” : 0, “count”: 10, “paginationToken”: “xydsad”}
}

40. • Code-generated response parser
• Bind model to native views
• Write once* per layout, reuse.
Client side rendering

41. Backward compatibility
{
“elements” : [
{“Stat”: {“Title”: “Your Profile...”, ...}},
{“JYMBII”: {“Title”: “5 Jobs you”, ...}},
{“Share”: {“Title”: “Swati Mathur...”, ...}},
....
],
“paging”: { “start” : 0, “count”: 10,
“paginationToken”: “xydsad”}
}
Drop unknown notification types.

42. Backward compatibility
Drop unknown fields based on product needs.

43. • New notification types without client
changes
• Renders faster on the client
Benefits

44. But… Client side Consistency is lost!

45. How do we solve this?

46. How did we solve the AttributedString problem?
• Model formatted text
• Control formatting from the server
• Impractical to use HTML
AttributedString

47. AttributedString schema
AttributedString
● Text: String
● Attributes: List[Attribute] BOLD, ITALIC, UNDERLINE etc.
Attribute
● Type: AttributeType
● StartIndex: Int
● Length: Int
● Metadata: Any?

48. Platform specific binding
Infrastructure provided support
iOS
Android
Web
NSAttributedString
Spannable
HTML
AttributedString

49. What if we extended this concept to entity mentions?
Model entity mentions also as a custom formatting specifier.
Profile mention Profile mention

50. Introducing TextViewModel
TextViewModel
● Text: String
● Attributes: List[TextViewAttribute]
TextViewAttribute
● Type: TextViewAttributeType
● StartIndex: Int
● Length: Int
● Metadata: Any?
● Profile: Profile?
● Job: Job?
● Company: Company?
● Course: Course?
Flattened canonical entities as optional fields
Similar to AttributedString

51. Entity mentions
Entities could be mentioned in different ways.
First Name
Full Name
Position

52. TextViewAttributeType
TextViewAttributeType
● PROFILE_FIRST_NAME
● PROFILE_FULL_NAME
● PROFILE_HEADLINE
● PROFILE_DISTANCE
● COMPANY_NAME
● COMPANY_HEADLINE
● JOB_TITLE
● ….
If a particular type is used, then the corresponding entity is populated by the server.
● PROFILE_XXX types will populate the profile field for example with the corresponding profile.

53. Backward compatibility++
Old clients cannot handle new mention types. Always send Raw text though redundant.
{
“title” : {
“Text”: “Sarah Clatterbuck shared this”,
“Attributes”: [
{“Type”: “PROFILE_FULL_NAME”,
“StartIndex”: 0….}
]
}
}

54. • Singular and Plurals
• Possessive forms
• i10n and i18n
Watch Out

55. How about images?
Use the same concept as TextViewModel. Introduce ImageViewModel.
ImageViewModel
● Attributes: List[ImageViewAttribute]
ImageViewAttribute
● ImageViewAttributeType
● URL: URL?
● ResourceName: String?
● Profile: Profile?
● Job: Job?
● Company: Company?
● Course: Course?
Flattened canonical entities as optional fields

56. ImageViewAttributeType
ImageViewAttributeType
● URL
● RESOURCE_NAME
● PROFILE_IMAGE
● PROFILE_BACKGROUND
● COMPANY_IMAGE
● ….
If a particular type is used, then the corresponding entity is populated by the server.
● PROFILE_XXX types will populate the profile field for example with the corresponding profile.
● URL type will populate the image URL
● RESOURCE_NAME will populate the pre-canned resource name.

57. Rendering Images
● Infra code extracts Image URL out of ImageViewModel
● Load into platform specific image view.
One Attribute: Regular ImageView
Multiple Attributes: GridImageView

58. Performance considerations
Entities may repeat multiple times within the same notification causing payload size bloat.
Tim’s Profile in ImageViewModel Tim’s Profile in TextViewModel

59. Solution: Response Normalization
All canonical entities have a unique ID. Use a JSON API like response format.
{
“data” : {
“Profile”: “profile:123”, ...
},
“included”: [
{
“id” : “profile:123”, “firstName” : “Tim”, “LastName” : “Jurka”, ... }
},
....
]
}

60. Performance considerations (Continued)
All fields from the entities may not be used.
ImageURL First Name and Last Name

61. Solution: Deco
Deco is a LinkedIn framework that allows selective projection and decoration of fields.
Profile in TextViewModel
ID
FirstName
LastName
Profile in ImageViewModel
ID
ImageURL
Profile in Response
ID
FirstName
LastName
ImageURL

62. Results

63. Improved Developer and Product Velocity
9 new notification types in all of 2016
16 new notification types in May and June 2017

64. API model reduction
42 API models for old UI
6 API models for new UI

65. Code size reduction
15k LOC app and test code for old UI
3k LOC app and test code for new UI

66. Future Direction
● Extend to other pages in Flagship
● Extend to other LinkedIn apps like JobSeeker, Recruiter etc.

67. Out of scope for this talk
● Intricate details of client side consistency management
● Generic Modeling of actions
● Challenges in migrating from the old notifications API to the new one
Find us after the talk, and we’re happy to chat about this and more.

68. Q & A
​amodi@linkedin.com
​https://www.linkedin.com/in/modiaditya/
​
​Aditya Modi
​kramgopal@linkedin.com
​https://www.linkedin.com/in/karthikrg/
​
​
​Karthik Ramgopal

69. Watch the video with slide
synchronization on InfoQ.com!
https://www.infoq.com/presentations/
linkedin-api-modeling