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

A. Introdução

Para facilitar novas integrações e manutenção do Gov.Doc API, propõem-se aplicar o padrão RESTful, pois é um padrão utilizado em todo o mundo, independente das tecnologias utilizadas (tipo linguagem de programação, framework etc). Assim sendo, analisou-se o código da aplicação, identificou-se as alterações necessárias e os impactos e levantou-se as demandas necessárias para atender ao objetivo de facilitar a implementação de novas integrações e manutenção da API.

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.