Dynamic Schema Generation for Changing Data Models

Designing *one* API is hard. Aiming to find the perfect sweet spot, a lot of decisions are to be made, so every API consumer gets what they need.
In our case the API surface changes between every single of our customers. Learn about design decisions & trade-offs when designing a *thousand* APIs at once.

Transcript

1. DYNAMIC SCHEMA GENERATION FOR CHANGING DATA MODELS
2. THERE ARE WELL-THOUGHT GRAPHQL APIS OUT THERE https://youtu.be/2It9NofBWYg - Leanne Shapton (Shopify) https://youtu.be/wPPFhcqGcvk - Kyle Daigle (GitHub)
3. GITHUB / SHOPIFY multiple users, but single schema every design decision is on point
4. CONTENTFUL content infrastructre customers define the shape of their content
5. SHIFT OF RESPONSIBILITY historically we decided how the API looks like now we only explain how the API is derived
6. OTHER OPTION Let the user describe the schema they want in SDL doubled effort when changing the shape hard for us to understand the user intention without new syntax
7. 1. DESIGN DECISION It's a greenfield view layer, not a greenfield app
8. at best, no changes to the models are needed the same internal data query adapter is used we can break with expectations where necessary
9. SECOND DESIGN DECISION Content Type IDs are used for type names
11. In the example before, everything is obvious: the type name should be Restaurant. But what about:
13. different name and ID name can be changed, ID cannot (auto-generated IDs can be invalid, starting with a number) Is it Category or FoodCategoryCuisine?
14. THIRD DESIGN DESCISION Content Type validations are re-used to derive links between types
17. NO LINKS DEFINED
18. WITH LINKS DEFINED
20. LATEST DESIGN DESCISION the generated type namespace is user-owned
21. fields like sys are colocated in the same namespace no fields indirection field IDs can be changed
22. USEFUL ERROR MESSAGES { errors: [{ message: "Schema generation failed. The type generated from the content type 'blog' contains a field with id 'sys' which is reserved.", extensions: { contentful: { code: 'RESERVED_FIELD_NAME', details: { contentTypeId: 'blog', fieldId: 'sys' }, requestId: 'xxx' } } }] }
23. THE END Twitter: @zcei_ger Slides: speakerdeck.com/zcei
24. https://graphql.contentful.com/content/v1/spaces/$SPACE_ID/explore