Resource Names

All new APIs shall adhere to the principles of REST. In doing so the following shall apply:

  • Separate things into logical Collections e.g. members
  • Collections are the collective term for Resources e.g. member
  • Resources are nouns, not verbs
  • Collections are plurals

Examples

  • /members - members is the collection name
  • /members/bob - Bob is the resource, he's a member

Exceptions

The only restriction is routes that have resource IDs that would match up to Personally Identifiable Information, or PII. If a resource name would collide with a piece of PII, you have two options:

  • Change the information to a key that's associated with the data
  • Use an RPC-style route

An RPC-style route may be used to facilitate the masking of data. For example, the following route would not be valid since it contains a phone number, which is classified as PII:

  • GET /numbers/15556667894
  • POST /numbers/15556667894
  • DELETE /numbers/15556667894

You can convert the above routes to something like the following:

  • POST /numbers/get with a payload of {"id": "15556667894"}
  • POST /numbers/update with a payload of {"id": "15556667894", "application_id": "abcd-1345-ddddd"}
  • POST /numbers/delete with a payload of {"id": "15556667894"}

Why did we choose this?

Pre-existing standard, based on Roy Fielding's dissertation