Beyond REST Coursera’s API Evolution Revisiting theoretical foundations to improve developer productivity. Brennan Saeta ! @bsaeta " saeta 

No content

No content

No content

Problems • Number of courses grew rapidly • Product needs changed: • premium course certificates • specializations • multi-university collaborations. • Growing size of engineering team 

Scale matters! In many dimensions • Queries per second • Data set size • Engineers • Types in ontology 

No content

Performance Requirements • Minimize data transfer across WAN • Minimize round trips Nice-to-have’s • Caching • ETag & Conditional Request Support • Binary Serialization 

No content

Experience- based APIs Queryable APIs 

Relational Algebra Meets REST/JSON APIs Projection: filter fields in response Selection: filter items in a collection Joins: related resources 

https://api.coursera.org/api/courses.v1?q=slug&slug=machine-learning response: { "elements": [ { "courseType": "v2.ondemand", "id": "Gtv4Xb1-EeS-ViIACwYKVQ", "name": "Machine Learning", "slug": "machine-learning" } ], "linked": {}, "paging": { "total": 1 } } request endpoint: /api/courses.v1 request query parameters: { "q": "slug", "slug": "machine-learning" } 

https://api.coursera.org/api/courses.v1?q=slug&slug=machine-learning &fields=primaryLanguages response: { "elements": [ { "courseType": "v2.ondemand", "id": "Gtv4Xb1-EeS-ViIACwYKVQ", "name": "Machine Learning", "slug": "machine-learning", "primaryLanguages": ["en"] } ], "linked": {}, "paging": { "total": 1 } } request endpoint: /api/courses.v1 request query parameters: { "q": "slug", "slug": "machine-learning", "fields": "primaryLanguages" } 

https://api.coursera.org/api/courses.v1?q=slug&slug=machine-learning &fields=instructorIds&includes=instructorIds response: { "elements": [ { "courseType": "v2.ondemand", "id": "Gtv4Xb1-EeS-ViIACwYKVQ", "name": "Machine Learning", "slug": "machine-learning", ”instructorIds": [1244] } ], "linked": { "instructors.v1": [ { "id": 1244, "name": "Andrew Ng" } ] }, "paging": { "total": 1 } } request endpoint: /api/courses.v1 request query parameters: { "q": "slug", "slug": "machine-learning", "fields": "instructorIds", "includes": "instructorIds" } 

https://api.coursera.org/api/courses.v1?q=slug&slug=machine-learning &fields=instructorIds,instructors.v1(title)&includes=instructorIds response: { "elements": [ { "courseType": "v2.ondemand", "id": "Gtv4Xb1-EeS-ViIACwYKVQ", "name": "Machine Learning", "slug": "machine-learning", "instructorIds": [1244] } ], "linked": { "instructors.v1": [ { "id": 1244, "name": "Andrew Ng", "title": "Associate Professor, Stanford University; Chief Scientist, Baidu; Chairman and Co-founder, Coursera" } ] }, "paging": { "total": 1 } } request endpoint: /api/courses.v1 request query parameters: { "q": "slug", "slug": "machine-learning", "fields": "instructorIds, instructors.v1(title)", "includes": "instructorIds" } 

0 200 400 600 800 Controllers vs Naptime Resources Controllers Resources 

Naptime Key Learnings • Leverage type safety, carefully • Collections of Key-Value pairs • Opinionated framework improves communication Principle: Optimize for developer productivity. 

Problems remained • Flattened representation difficult for clients • URL representation cumbersome • Auto-doc tools not useable 

Problems remained • Flattened representation difficult for clients GraphQL queries are easy to read, modify, and maintain • URL representation cumbersome GraphQL queries are easy to read, modify, and maintain • Auto-doc tools not useable GraphiQL supports auto-completion and inline documentation 

No content

GraphQL Query: query { CoursesV1Resource { slug(slug: "machine-learning") { id } } } request endpoint: /api/courses.v1 request query parameters: { "q": "slug", "slug": "machine-learning" } 

request endpoint: /api/courses.v1 request query parameters: { "q": "slug", "slug": "machine-learning", "fields": "primaryLanguages" } GraphQL Query: query { CoursesV1Resource { slug(slug: "machine-learning") { id primaryLanguages } } } 

request endpoint: /api/courses.v1 request query parameters: { "q": "slug", "slug": "machine-learning", "fields": "instructorIds", "includes": "instructorIds" } GraphQL Query: query { CoursesV1Resource { slug(slug: "machine-learning") { id instructors: instructorIds { id } } } } 

request endpoint: /api/courses.v1 request query parameters: { "q": "slug", "slug": "machine-learning", "fields": "instructorIds, instructors.v1(title)", "includes": "instructorIds" } GraphQL Query: query { CoursesV1Resource { slug(slug: "machine-learning") { id instructors: instructorIds { id title } } } } 

Edge Tier GraphQL Assembler Profile Service Enrollments Service Catalog Service 

Edge Tier GraphQL Assembler Profile Service Enrollments Service Catalog Service 

No content

Key Lessons Learned Carefully understand your problem Look to theory: stand on the shoulders of giants Plug into the ecosystem 

Naptime is developed in the open https://github.com/coursera/naptime 

Thank you! 

Thank you! 

Questions? 

Thank you! Photo Credits: Trevor Wilson — https://unsplash.com/@clevertrevor Pablo Garcia Saldaña — https://unsplash.com/@pagsa_ Rob Bye — https://unsplash.com/@robertbye Eli Francis - https://unsplash.com/@elifrancis Ryan Hafney — https://unsplash.com/@ryanhafey Thank you: Bryan Kane & Coursera Colleagues