Share
Embed
Transcript
17 slides
-
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/<entity>.json /debug/<entity>.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/