Formação e Estabilidade do ID

Owned by Eloisa de Oliveira Santos (Unlicensed)
jun. 22, 2023

Dentro desses padrões, a serem melhor especificados a partir da Fase 2 do Open Insurance no Brasil, os IDs de recursos são necessários para atender ao seguinte:

  • O ID de um recurso deve ser especificado no endpoint de uma API apenas para obter detalhes do recurso ou para realizar alterações no mesmo.

  • Se o ID for especificado nos padrões do Open Insurance, então ele é obrigatório e deverá ser fornecido pela entidade implementadora da API de acordo com o padrão definido.

  • Se um ID for especificado, o mesmo deverá ser totalmente desconectado de significados com outras entidades. Por exemplo, um ID não deve ser uma combinação de outros campos ou uma string que possa ter conteúdo sensível que possa ser extraído.

  • Os IDs devem ser únicos, e sua padronização será detalhada a partir da Fase 2 do Open Insurance no Brasil, porém sua unicidade pode estar dentro de um contexto. Por exemplo, um ID de apólice deve ser único, porém apenas dentro do contexto de apólice.

  • Nos payloads o nome de campo "id" nunca deverá ser utilizado. Cada campo ID deverá ter um nome significativo, dessa forma independentemente de onde o ID for utilizado entre múltiplos endpoints, ele sempre irá se referir ao seu objeto principal. Por exemplo, IDs para apólices deverão ser representados no JSON como "policyId".

Princípios para a formação de IDs (identificadores) de recursos nas APIs

  • O ID DEVE ser uma string com limitação de 100 caracteres - limite que poderá ser revisitado em caso de necessidade apresentada por quaisquer dos participantes do Open Insurance Brasil e - aderente aos padrões apresentados na seção 2.1 da RFC 2141;

  • Uma vez que será trafegado nas chamadas de interface, o ID NÃO DEVE conter dados classificados como PII - Personally identifiable information (Informação Pessoalmente Identificável) ou Informação de Identificação Pessoal;

  • DEVE ser garantida a unicidade do ID dentro do contexto da API assim como a estabilidade do mesmo, sendo a estabilidade condicionada à manutenção das características de identificação natural do recurso em questão. A alteração das características de identificação natural implica na geração de um novo identificador associado ao recurso;

  • A utilização de meios técnicos razoáveis e disponíveis para a formação do ID é de livre implementação por parte da instituição transmissora dos dados, de forma que apenas a aderência aos princípios elencados nesta documentação é mandatória.