API Notes

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


  • 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

Rate limiting

  • 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