API Conference

REST APIs - Good practices

Transcript

1. Rest API - Good practices François Terrier / Liip AG API Conference - 1.9.2015 - Zürich
2. 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
3. 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
4. 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
5. 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
6. 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
7. 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
8. 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
9. 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
10. … 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.- ….
11. 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
12. Alerting/Monitoring/Troubleshooting Data imports? • Detect inconsistencies before your clients do REST API • Detect weird traffic pattern • When to scale? And how to scale?
13. 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/<entity>.json /debug/<entity>.json
14. 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
15. 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/
16. Thanks ! Questions ?
17. Step xx: master slide