names follow us everywhere, so it’s important to choose great names.
Why do names matter?
- without a name, it is unreadable at best.
- we need to put an extraordinary amount of thought and consideration into the name we choose for an API.
- “Can’t we just change the names if they turn out to be bad choices?” — Yes, but very hard.
- Changing public-facing names in an API is a bit like changing your phone number.
What makes a name “good”?
- prevent user confusion e.g. ‘model_topic’, ‘messaging_topic’ insteads of ‘topic’.
- names should be expressive, but not excessively long.
- ‘topic’ is good enough when we touch only one area like messaging while ‘messaging_topic’ wouldn’t add much value.
good — transactions
/accounts/{account_id}/transactions- This resource allows the user to view a list of all transactions made on a specific account./accounts/{account_id}/transactions/{transaction_id}- This resource allows the user to view the details of a specific transaction./accounts/{account_id}/transactions/transfer- This resource allows the user to make a transfer between accounts.
confusing — trans, tran_details, money_transfer
/accounts/{account_id}/trans- This resource allows the user to view a list of all transactions made on a specific account./accounts/{account_id}/tran_details/{transaction_id}- This resource allows the user to view the details of a specific transaction./accounts/{account_id}/money_transfer- This resource allows the user to make a transfer between accounts.
