Upgrade to Pro — share decks privately, control downloads, hide ads and more …

API Conference

API Conference

REST APIs - Good practices

François Terrier

September 01, 2015

Other Decks in Technology


  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/