Definitions - Remove resource identifier examples from 'definitions' that potentially expose PII

[TimGoodwill]

Seeking the removal resource identifier examples from 'definitions' that potentially expose Personally identifiable information (PII), specifically "/employees/john-smith". Also seeking the addition of an injunction against exposing PII and primary keys.

Suggested change:

Resource Identifier
Every resource that is available within your system (e.g. every employee or every leave-request) must be identifiable uniquely within the system. This is a key element of the RESTful style of APIs; the ability to individually address any item within your system and store these identifiers for later use.

Resource identifiers can be any of the following:

Name	Example
Numeric	/employees/12389
String	/country-codes/australia
GUID	/employees/0d047d80-eb69-4665-9395-6df5a5e569a4
Date (Short form)	/dates/2018-09-17

As long as the identifier is unique within your application it can be any string of characters or numbers.

The resource identifier MUST be immutable. Primary keys or Personally Identifiable Information (PII) MUST NOT be exposed. When numeric IDs are used they MUST NOT be sequential e.g. it should not be trivial to guess the next ID. If this is difficult to achieve, then it is likely the API needs to be further abstracted from the underlying data source.

[rahariya]

@TimGoodwill

Can "The resource identifier MUST be immutable" be removed from the suggested change?

A primary key is usually made up of whatever tuples are necessary to determine uniqueness for a record. Whether the data can change or not might not be relevant. Only the uniqueness of the record is what that matters. That is the conceptual design of the database.

[TimGoodwill]

Can "The resource identifier MUST be immutable" be removed from the suggested change?

I wouldn't die in a ditch to keep it in for the interim update - it is at least an iteration in the right direction.
However a resource identifier SHOULD be immutable, and although edge cases undoubtedly exist, I cant think of good one.

A URI - literally 'Uniform Resource Identifier' - should not change, and is often stored by API consumers. A different URI implies a different resource. A resource will have a state lifecycle, and state change events are tied immutably to that resource identifier, to which consumers may be subscribed. Ideally a resource identifier will be a unique, non-guessable and non-sequential alphanumeric string (such as a GUID) that does not expose a DB primary key.

A GET can be performed on a resource collection filtering for fields such as email address using query params - mutable data should never be used a primary key.