Desigining the new GoCardless API

Transcript

1. Designing the new GoCardless API Harry Marr and Philip Harrison
3. GrouPAY API
4. GrAPI
6. 1. Agile API development 2. Build your framework 3. Prepare for change
7. HOW TO BUILD PRODUCTS
12. Work out what people want Build it
13. Work out what people want Build it Work out what people really want
14. Work out what people want Build it Work out what people really want
15. HOW TO BUILD APIS
16. Work out what people want Build it
17. Work out what people want Build it Work out what people really want
18. Work out what people want Build it Work out what people really want Uh oh!
19. Changing a product is easy Changing your API is hard
20. 1. Agile API development 2. Build your framework 3. Prepare for change
21. MAKING IT LAST
22. • Content Type • Document/url structure • TLS/SSL • Pagination • Rate-limiting • Errors
23. CONTENT TYPE
24. { "payment": { "xmlns": "urn:ns:payment", "amount": { "$t": 20000 }, "metadata": { "type": "metadata", "xmlns": "urn:ns:metadata", "description": { "$t": "Rent" } } } }
25. { "payment": { "amount": 20000, "metadata": { "description": "Rent" } } } https://www.mnot.net/blog/2012/04/13/json_or_xml_just_decide
26. DOCUMENT/URL STRUCTURE
27. { "linked": { "author": { "id": "12" } }, "posts": [{ "id": "1", "title": "API", "links": { "author": "12" } }] } http://jsonapi.org/format/
28. /customers/1/bank_accounts/2/mandates/1 Don’t map database relations to urls
29. /mandates?bank_account=2 /customer_bank_accounts?customer=1 Flexible relationships
30. TLS/SSL All traffic including web hooks https://istlsfastyet.com/
31. PAGINATION
32. /payments { "meta": { "cursors": { "after": "abcd1234", "before": "wxyz0987" }, "limit": 50 }, "payments": [{ ... }] } /payments?limit=50&after=abcd1234
33. RATE-LIMITING
34. X-Rate-Limit-Limit: 5000 X-Rate-Limit-Remaining: 0 X-Rate-Limit-Reset: Thu, 01 May 2014 16:00:00 GMT Content-Type: application/json; charset=utf-8 Connection: keep-alive Retry-After: Thu, 01 May 2014 16:00:00 GMT
35. ERRORS
36. { "error": { "documentation_url": “https://errors", "id": “ERROR_ID”, "type": "validation_failed”, "code": 422, "errors": [{ "field": "account_number", "type": "missing_field", "message": "is required" }] } }
37. GoCardless API design https://github.com/gocardless/http-api-design
38. 1. Agile API development 2. Build your framework 3. Prepare for change
39. Work out what people want Build it Work out what people really want Uh oh!
40. Work out what people want Build it Work out what people really want
41. ✓ Adding resources ✓ Adding attributes ✗ Removing attributes ✗ Changing attributes ✗ Removing resources ✗ Changing behaviour
42. /v1
43. /v1
44. v1
45. 2014-08-13
46. /2014-08-13
47. 2014-08-13
48. You are currently using version 2014-­‐05-­‐12.   ! Click here to view all changes since 2014-­‐05-­‐12. To: developer@gmail.com From: help@gocardless.com GoCardless API Update Available
49. In summary, • Developing an API is hard • Think about what you can’t change • And plan for incremental updates
50. QUESTIONS? ! @harrymarr @harrisonphilip