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

A. Introdução

Para facilitar tanto novas integrações quanto manutenção do Gov.Doc API, aaplicar padronização da APIpadrão RESTful deve ajudar pois é um padrão utilizado em todo o mundo.mundo, independente das tecnologias utilizadas (tipo linguagem de programação, framework etc). 

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.