Design principles for your HTTP APIs

  • Impose consistency so that similar endpoints behave in similar ways, even in edge scenarios, with consistent vocabulary, URL structure, request/response formats and error handling. This will help ensure that users don’t need to read extensive documentation and handling updates becomes easier for developers.
  • Achieve performance by avoiding early optimization, waiting until you have the right metric in place to optimize based on hard data - and collect that data from day one, with an APM tool.
  • Use metrics to inform evolution, so that you update and add features based on actual user usage of endpoints to avoid or minimize disruptions to existing implementations.
  • For complex APIs, avoid a 1:1 mapping between database tables and API resources. Build in usability by simplifying business transactions to require a single API call rather than multiple. If it isn’t possible, be as flexible as you can.
  • Adopt simplicity by building on top of universally accepted standards and tools. This will mean less overheads and less room for mistakes.

Full post here, 7 mins read