[Gov.Doc-API] Padronizar a API para RESTful

Data de elaboração	05/12/2022
Responsável pelo estudo	Nara Carolina Galvão Feitosa Raissa de Sousa Stodulski Taillon Miguel Gonçalves Ádelle Camarão Monteiro
Equipe do estudo	Tambakiss
Alvo	Gov.Doc API
Origem	Implementação para facilitar novas e atuais integrações ao seguir o padrão RESTful
Objetivo	Com a padronização, deve facilitar a manutentação da API além de que deve facilitar novas integrações.
Documentação correlata (opcional)
Observações

A. Introdução

Para facilitar tanto novas integrações quanto manutenção do Gov.Doc API, a padronização da API RESTful deve ajudar pois é utilizado em todo o mundo.

B. Alterações necessárias

1. Para todas as controllers

1.1. Implementar middleware para tratamento de erro para quando estourar um erro, retornar 500-InternalServerError com a mensagem da exceção que estourou.

[Storia] Eu, como SETIC, preciso criar middleware para tratamento de erro
- Por quê? Para padronizar o retorno dos endpoints quando houver um erro não esperado.
- Regras: Aplicar a controller Modelos para servir de exemplo.
[Storia] Eu, como SETIC, preciso implementar o middleware na controller BlocoDeAssinatura
[Storia] Eu, como SETIC, preciso implementar o middleware na controller Documentos

1.2. Criar um BaseService onde há um tratamento para mensagens de validação. Quando retornar a(s) validação(s) para a controller e o endpoint identificar/retornar 400-BadRequest com a(s) mensagem(s) de validação.

[Storia] Eu, como SETIC, preciso criar o BaseService para tratamento de validações
- Por quê? Para padronizar o retorno dos endpoints quando cair em alguma regra/validação.
- Regras: Aplicar a controller Modelos para servir de exemplo.
[Storia] Eu, como SETIC, preciso implementar o BaseService no service do BlocoDeAssinatura
[Storia] Eu, como SETIC, preciso implementar o BaseService no service do Documentos

1.3. Padronizar o retorno de bem-sucedido dos endpoints, devem retornar 200-Success com uma mensagem de sucesso ou o objeto atualizado/criado. E renomear viewModel para dto pois sem view, é dto.

[Storia] Eu, como SETIC, preciso padronizar o retorno de 200-Success de todos os endpoints da controller Modelos
- Por quê? Pois deve seguir o padrão RESTful.
- Regras:
  - Deve retornar o objeto criado/alterado/consultado (quando é GET/POST/PUT/PATCH) ou uma mensagem de bem-sucedido (para os outros como DELETE/PATCH).
  - Renomear viewModel para dto.
[Storia] Eu, como SETIC, preciso padronizar o retorno de 200-Success de todos os endpoints da controller BlocoDeAssinatura
- Por quê? Pois deve seguir o padrão RESTful.
- Regras:
  - Deve retornar o objeto criado/alterado/consultado (quando é GET/POST/PUT/PATCH) ou uma mensagem de bem-sucedido (para os outros como DELETE/PATCH).
  - Renomear viewModel para dto.
[Storia] Eu, como SETIC, preciso padronizar o retorno de 200-Success de todos os endpoints da controller Documentos
- Por quê? Pois deve seguir o padrão RESTful.
- Regras:
  - Deve retornar o objeto criado/alterado/consultado (quando é GET/POST/PUT/PATCH) ou uma mensagem de bem-sucedido (para os outros como DELETE/PATCH).
  - Renomear viewModel para dto.

2. BlocoDeAssinaturaController

2.0. [Storia] Eu, como SETIC, preciso renomear controller BlocoDeAssinatura para BlocosDeAssinatura.

Por quê? Pois o padrão é a controller estar no plural.

2.1. Ajustar endpoint na controller atual

2.1.1. [Storia] Eu, como SETIC, preciso aplicar padrão RESTful no método Consultar da controller BlocoDeAssinatura.

[Task] Renomear método para Buscar

2.1.2. [Storia] Eu, como SETIC, preciso aplicar padrão RESTful no método Criar da controller BlocoDeAssinatura

[Task] Alterar rota do endpoint BlocosDeAssinatura/Criar para BlocosDeAssinatura
[Task] Remover campo BlocoId do body

2.1.3. [Storia] Eu, como SETIC, preciso aplicar padrão RESTful no método Editar da controller BlocoDeAssinatura

[Task] Alterar rota do endpoint para pegar o BlocosDeAssinatura para BlocosDeAssinatura/{id}
[Task] Remover campo BlocoId do body

2.1.4. [Storia] Eu, como SETIC, preciso aplicar padrão RESTful no método AdicionarDocumento da controller BlocoDeAssinatura

[Task] Alterar rota do endpoint para pegar o BlocosDeAssinatura/AdicionarDocumento para BlocosDeAssinatura/{id}/AdicionarDocumento
[Task] Remover campo BlocoId do body
[Task] Alterar método HTTP para PATCH

2.1.5. [Storia] Eu, como SETIC, preciso aplicar padrão RESTful no método RemoverDocumento da controller BlocoDeAssinatura

[Task] Alterar rota do endpoint para pegar o BlocosDeAssinatura/RemoverDocumento para BlocosDeAssinatura/{id}/RemoverDocumento
[Task] Remover campo BlocoId do body
[Task] Alterar método HTTP para PATCH

2.1.6. [Storia] Eu, como SETIC, preciso aplicar padrão RESTful no método DisponibilizarParaAssinatura da controller BlocoDeAssinatura

[Task] Alterar rota do endpoint para pegar o BlocosDeAssinatura/DisponibilizarParaAssinatura para BlocosDeAssinatura/{id}/Disponibilizar
[Task] Remover campo IdDoBloco do body
[Task] Alterar método HTTP para PATCH
[Task] Renomear método para Disponibilizar

2.1.7. [Storia] Eu, como SETIC, preciso aplicar padrão RESTful no método Assinar da controller BlocoDeAssinatura

[Task] Alterar rota do endpoint para pegar o BlocosDeAssinatura/Assinar para BlocosDeAssinatura/{id}/Assinar
[Task] Remover campo IdDoBloco do body
[Task] Alterar método HTTP para PATCH

2.1.8. [Storia] Eu, como SETIC, preciso aplicar padrão RESTful no método Excluir da controller BlocoDeAssinatura

[Task] Alterar rota do endpoint para pegar o BlocosDeAssinatura/Excluir para BlocosDeAssinatura/{id}
[Task] Remover campo IdDoBloco do body

2.1.9. [Storia] Eu, como SETIC, preciso aplicar padrão RESTful no método Cancelar da controller BlocoDeAssinatura

[Task] Alterar rota do endpoint para pegar o BlocosDeAssinatura/Cancelar para BlocosDeAssinatura/{id}/Cancelar
[Task] Remover campo IdDoBloco do body
[Task] Alterar método HTTP para PATCH

2.1.10. BlocosDeAssinatura/Cpf/{cpf}

Sem alterações.

2.2. Ajustar endpoint e mover para nova controller BlocosDeAssinaturaPorSistema

2.2.1. [Storia] Eu, como SETIC, preciso aplicar padrão RESTful no método CriarPorSistema da controller BlocoDeAssinatura

[Task] Alterar rota do endpoint para pegar o BlocosDeAssinatura/CriarPorSistema para BlocosDeAssinaturaPorSistema
[Task] Remover campo BlocoId do body
[Task] Renomear método para Criar

2.2.2. [Storia] Eu, como SETIC, preciso aplicar padrão RESTful no método AdicionarDocumentoPorSistema da controller BlocoDeAssinatura

[Task] Alterar rota do endpoint para pegar o BlocosDeAssinatura/AdicionarDocumentoPorSistema para BlocosDeAssinaturaPorSistema/{id}/AdicionarDocumento
[Task] Alterar método HTTP para PATCH
[Task] Remover campo BlocoId do body
[Task] Renomear método para AdicionarDocumento

2.2.3. [Storia] Eu, como SETIC, preciso aplicar padrão RESTful no método RemoverDocumentoPorSistema da controller BlocoDeAssinatura

[Task] Alterar rota do endpoint para pegar o BlocosDeAssinatura/RemoverDocumentoPorSistema para BlocosDeAssinaturaPorSistema/{id}/RemoverDocumento
[Task] Alterar método HTTP para PATCH
[Task] Remover campo BlocoId do body
[Task] Renomear método para RemoverDocumento

2.2.4. [Storia] Eu, como SETIC, preciso aplicar padrão RESTful no método Excluir da controller BlocoDeAssinatura

[Task] Alterar rota do endpoint para pegar o BlocosDeAssinatura/ExcluirPorSistema para BlocosDeAssinaturaPorSistema/{id}
[Task] Remover campo BlocoId do body
[Task] Renomear método para Excluir

2.2.5. [Storia] Eu, como SETIC, preciso aplicar padrão RESTful no método Cancelar da controller BlocoDeAssinatura

[Task] Alterar rota do endpoint para pegar o BlocosDeAssinatura/CancelarPorSistema para BlocosDeAssinaturaPorSistema/{id}/Cancelar
[Task] Alterar método HTTP para PATCH
[Task] Remover campo IdDoBloco do body
[Task] Renomear método para Cancelar

3. DocumentosController

3.1. Ajustar endpoint na controller atual

3.1.1. [Storia] Eu, como SETIC, preciso aplicar padrão RESTful no método GetDocumento da controller Documentos

[Task] Renomear método para Buscar

3.1.2. [Storia] Eu, como SETIC, preciso aplicar padrão RESTful no método ConsultarHistorico da controller Documentos

[Task] Alterar rota do endpoint para pegar o Documentos/Historico/{id} para Documentos/{id}/Historico
[Task] Renomear método para BuscarHistorico

3.1.3. [Storia] Eu, como SETIC, preciso aplicar padrão RESTful no método PostDocumento da controller Documentos

[Task] Renomear método para Criar

3.1.4. [Storia] Eu, como SETIC, preciso aplicar padrão RESTful no método PostDocumentoUsuarioExterno da controller Documentos

[Task] Alterar rota do endpoint para pegar o Documentos/PostDocumentoUsuarioExterno para Documentos/UsuarioExterno
[Task] Renomear método para Criar

3.1.5. [Storia] Eu, como SETIC, preciso aplicar padrão RESTful no método PutDocumento da controller Documentos

[Task] Alterar rota do endpoint para pegar o Documentos para Documentos/{id}
[Task] Remover campo Id do body
[Task] Renomear método para Editar

3.1.6. [Storia] Eu, como SETIC, preciso aplicar padrão RESTful no método Compartilhar da controller Documentos

[Task] Alterar rota do endpoint para pegar o Documentos/Compartilhar para Documentos/{id}/Compartilhar
[Task] Alterar método HTTP para PATCH
[Task] Remover campo IdDocumento do body

3.1.7. [Storia] Eu, como SETIC, preciso aplicar padrão RESTful no método Arquivar da controller Documentos

[Task] Alterar rota do endpoint para pegar o Documentos/Arquivar para Documentos/{id}/Arquivar
[Task] Alterar método HTTP para PATCH
[Task] Remover campo Id do body

3.1.8. [Storia] Eu, como SETIC, preciso aplicar padrão RESTful no método Assinar da controller Documentos

[Task] Alterar rota do endpoint para pegar o Documentos/Assinar para Documentos/{id}/Assinar
[Task] Alterar método HTTP para PATCH
[Task] Remover campo IdDocumento do body

3.1.9. [Storia] Eu, como SETIC, preciso aplicar padrão RESTful no método Revogar da controller Documentos

[Task] Alterar rota do endpoint para pegar o Documentos/Revogar para Documentos/{id}/Revogar
[Task] Alterar método HTTP para PATCH
[Task] Remover campo IdDocumento do body

3.1.10. [Storia] Eu, como SETIC, preciso aplicar padrão RESTful no método VerificarAutenticidade da controller Documentos

[Task] Alterar rota do endpoint para pegar o Documentos/Autenticidade para Documentos/{id}/Autenticidade
[Task] Alterar método HTTP para GET
[Task] Renomear método para Autenticar

3.1.11. Documentos/Pdf/{id}

Sem alterações

3.1.12. [Storia] Eu, como SETIC, preciso aplicar padrão RESTful no método BuscarPorCpf da controller Documentos

[Task] Criar novo filtro [FromQuery] SomenteArquivados: bool?
[Task] Aplicar filtro SomenteArquivados, igual o método BuscarArquivadoPorCpf pois ele será deletado.

3.1.13. [Storia] Eu, como SETIC, preciso aplicar padrão RESTful no método BuscarPorCpf da controller Documentos

[Task] Alterar rota do endpoint para pegar o Documentos/Numeracao?numeracao={numeração} para Documentos?numeracao={numeração}

3.1.14. Documentos/Arquivado/Cpf/{cpf}

Sem alterações.

3.2. Ajustar endpoint e mover para nova controller DocumentosPorSistema

3.2.1. [Storia] Eu, como SETIC, preciso aplicar padrão RESTful no método Compartilhar da controller Documentos

[Task] Alterar rota do endpoint para pegar o Documentos/ CompartilharPorSistema para DocumentosPorSistema/{id}/Compartilhar
[Task] Alterar método HTTP para PATCH
[Task] Remover campo IdDocumento do body
[Task] Renomear método para Compartilhar

4. ModelosController

4.1. Modelos

Sem alterações.

4.1. Modelos/{id}

Sem alterações

Há ainda novas actions e controllers a serem criadas.

C. Conclusão

Concluímos que essas alterações necessárias para aplicar o padrão RESTful. O projeto ainda é passível de outras melhorias na arquitetura, nomenclatura de classes, métodos e variáveis, melhorias nos testes unitários e nos testes de integração.