Rest API - Good practices François Terrier / Liip AG API Conference - 1.9.2015 - Zürich 

You’ve got a situation Use data on the web but… • Existing system with slow components • Data not in the appropriate format for the web • Lots of systems / One monolithic system • Hard/expensive to scale 

Building a Rest API - Steps 1. Bring the data to the right format • Consistency 2. Make it fast and scalable • Layering, Caching 3. Get people to use it • Documentation 4. Maintain and develop • Alerting/Monitoring • BC-Breaks + Versioning 5. What’s next? Current trends 

Bring data to the right format Data 1 Data 2 Data 3 … DB ElasticSearch MongoDB … Extract Transform/Load Legacy systems Slow access? Not dedicated Copy of the data Fast access Dedicated No format change Desired format Fast access 

But which format? curl -XGET /my-data.json ElasticSearch MongoDB Web Server Client REST Desired format ? 1. Check other people’s work, standards, open-source 2. Talk to users (remember: your users are developers) 3. Keep it simple & Iterate 

Make it scale and make it fast More features - How to keep adding features? API More requests More features More requests - Horizontal scaling: not so hard - Caching is challenging 

More features - Client requirements Clients need slightly optimised version of the API fields, or aggregations. curl -XGET /my-data.json curl -XGET /my-related-data.json + 2 calls and potentially a lot of data 

Layer and compose curl -XGET /my-data.json API Client curl -XGET /my-related-data.json App API 1. Development teams can be separate 2. API can focus on adding new data curl -XGET /aggregated-data.json 

More requests - Caching curl -XGET /my-data.json API Client curl -XGET /my-related-data.json App API curl -XGET /aggregated-data.json Cache here ? Cache there ? 1. Start caching closest to the source 2. Only cache on clients if strictly necessary • Cache invalidation is hard 

… and invalidation What should we invalidate when some data changes? 2.40 2.50 3.- 3.50 1000.- 1500.- …. Page 1 Page 2 Page 100 2.40 2000.- 2.50 3.- 3.50 4.- 1500.- 2000.- …. 

Consistency! • Pick a language and stick to it • CamelCase vs. snake_case vs. lisp-case • Avoid confusing names for fields Self-documenting JSON fields are not enough • Relationship between fields - IDs • Documentation of changes • Migration guides • Tutorials Allow this : Get people to use it 

Alerting/Monitoring/Troubleshooting Data imports? • Detect inconsistencies before your clients do REST API • Detect weird traffic pattern • When to scale? And how to scale? 

A lot can go wrong … Data 1 Data 2 Data 3 … DB ElasticSearch MongoDB … Extract Transform/Load curl -XGET /my-data.json API Client curl -XGET /my-related-data.json App API curl -XGET /aggregated-data.json /debug/db/.json /debug/.json 

Versioning Only create a new version when strictly necessary! ElasticSearch MongoDB API Client curl -XGET -H “Api-Version: 2” curl -XGET -H “Api-Version: 1” Legacy Client no version here ElasticSearch MongoDB v1 API Client curl -XGET -H “Api-Version: 2” curl -XGET -H “Api-Version: 1” Legacy Client ElasticSearch MongoDB v2 v1 v2 

Rest API - Trends & Alternatives Until now: • Stateless APIs, Layering, Micro-Services Future: • Still stateless • React and data Pull APIs • https://facebook.github.io/graphql/ • http://netflix.github.io/falcor/ 

Thanks ! Questions ? 

Step xx: master slide