Lessons Learned from the gocardless guys
- Notes taken during presentation by Go Cardless at Facebook London on Oct 13, 2014 at the London API meetup
- Changing your api is really hard
- Define list of hard things to change
Hard Things to Change in an API Design
- Json or XML. - pick one and support it. Do not support both
Document URL structure
- most phylisophical discussions
- jsonapi apec that defines everything. Better o be consistent than correct.
- don't map database relations to URLs. URLs can not change. Db relations can always xhNge
*- use filtering eg ? Instead
- enforce it always and do it up front
- very hard to do.
- Think about what scheme works beat for your api and put it in place right away
- Make it easy to deal with
- Think of all expected errors and define how they should look.
- Put links to documentation in the error messages that you're sending back
- Put all your errors and ID's in your documentation
- Create a living API document
- Go cardless used the "json api designer" and generated API documenation which lives on the gocardless github page
Prepare for change
Error format and how you do pagination can not change. So design it well at the beginning
Adding new resources = OK
Adding attributes = OK
Removing attributes = FAIL
Removing anything = FAIL
Why no /v1?
- Everyone thinks its an enormous release
Use Date instead
- Use the date inatead. /2014-08-13/
- Allows for incremental releases