Improve identifier types

[swallez]

We have a number of types for identifiers (see common.ts) which are used more or less consistently in the API spec.

Currently their role and purpose may not be obvious (what is Id, what is Name?). We should:

• document these types
• add a new DocId type for document identifiers. It should replace Id everywhere it is used as document identifier.
• Id should be kept as a general-purpose string type that distinguishes between unique identifiers in the system (be them internal or external identifiers) and text strings.