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

Content type

• 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

TLS SSL

• enforce it always and do it up front

Pagination

• very hard to do.
• Think about what scheme works beat for your api and put it in place right away

Rate limiting

• Make it easy to deal with

Errors

• 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

Versioning

Why no /v1?

• Everyone thinks its an enormous release

Use Date instead

• Use the date inatead. /2014-08-13/
• Allows for incremental releases