• Padrão de nomenclatura

     Sempre utilizar plural ao disponibilizar o recurso:
     Não usar: GET /orgao, usar GET /orgaos.

     Sempre utilizar minúsculo nos recursos:
     Não usar: GET /Orgaos, usar GET /orgaos.

     Sempre utilizar substantivos nos recursos CRUD:.
     Não usar: GET /orgaos/consultar, usar GET /orgaos.
     Não usar: POST /orgaos/incluir, usar POST /orgaos.
     Não usar: PUT /orgaos/CELEPAR/alterar, usar PUT /orgaos/CELEPAR.
     Não usar: DELETE /orgaos/CELEPAR/excluir, usar DELETE /orgaos/CELEPAR.

     Obs.: Não utilizar camelCase, PascalCase, snake_case ou kebab-case nos recursos.


• Definição de recursos

     A raiz do recurso deve retornar uma coleção:
     O recurso GET /orgaos deve retornar um lista de órgãos.

     Se desejar obter um recurso especifico, utilizar o nível seguinte especificando seu identificador único:.
     O recurso GET /orgaos/CELEPAR deve retorna o órgão CELEPAR.

     • GET /orgaos -> Retorna uma lista de órgãos.
     • GET /orgaos/CELEPAR -> Retorna o órgão de código CELEPAR.
     • POST /orgaos -> Cria um órgão.
     • PUT /orgaos/CELEPAR -> Atualiza o órgão CELEPAR.
     • DELETE /orgaos/CELEPAR -> Remove o órgão CELEPAR.


• Relacionamento filho

     Se existir alguma tabela filho do recurso, eles devem estar mapeados para o mesmo endpoint:

     • GET /orgaos/CELEPAR/locais -> Retorna uma lista de locais do órgão CELEPAR.
     • GET /orgaos/CELEPAR/locais/CELEP/COS-B3 -> Retorna o local CELEP/COS-B3 do órgão CELEPAR.
     • POST /orgaos/CELEPAR/locais -> Cria um novo local para o órgão CELEPAR.
     • PUT /orgaos/CELEPAR/locais/CELEP/COS-B3 -> Atualiza a local CELEP/COS-B3 do órgão CELEPAR.
     • DELETE /orgaos/CELEPAR/locais/CELEP/COS-B3 -> Remove o local CELEP/COS-B3 do órgão CELEPAR.

     Obs.: Evitar que os endpoints tenham mais de 3 níveis, por exemplo: /nivel1/{codigo}/nivel2/{codigo}/nivel3/{codigo}.


• Ações

     Frequentemente é necessário realizar operações que diferem das operações normais de CRUD. Neste caso deve-se utilizar verbos para nomear operações de ação.
     Obs.: Os serviços de ações são sempre serviços PUT.

     Por exemplo:

     • PUT /protocolos/{protocolo}/tramitacoes/bloquear
     • PUT /volumes/{protocolo}/documentos/{codigo}/cancelar

• Padrão dos escopos

     Os escopos da Central de Segurança devem acompanhar o endpoint do serviço.

     Por exemplo, para o serviços CRUD:

     • GET /protocolos/{protocolo}/anexos -> spiserv.protocolos.anexos.consultar
     • GET /protocolos/{protocolo}/anexos/{codigo} -> spiserv.protocolos.anexos.consultar
     • POST /protocolos/{protocolo}/anexos -> spiserv.protocolos.anexos.incluir
     • PUT /protocolos/{protocolo}/anexos/{codigo} -> spiserv.protocolos.anexos.alterar
     • DELETE /protocolos/{protocolo}/anexos/{codigo} -> spiserv.protocolos.anexos.excluir

     Obs.: Serviços de listar (retornam uma lista de determinado recurso) e de consultar (retorna um determinado recurso em específico) devem ter o mesmo escopo.

     Para os serviços de ações:

     • PUT /protocolos/{protocolo}/tramitacoes/bloquear -> spiserv.protocolos.tramitacoes.bloquear
     • PUT /volumes/{protocolo}/documentos/{codigo}/cancelar -> spiserv.volumes.documentos.cancelar

     Alguns serviços podem ter o mesmo escopo para todos os endpoints, pois não faria sentido ter escopos diferentes, o que só aumentaria a complexidade do uso.

     Por exemplo:

     • GET /localidades/paises -> spiserv.localidades.consultar
     • GET /localidades/estados -> spiserv.localidades.consultar
     • GET /localidades/estados/PR/municipios -> spiserv.localidades.consultar

• Parâmetros utilizados pelo webservice do eProtocolo

     Existem quatro tipos diferentes de parâmetros aceitos pelo spi-servicos:

     • Path Parameters
     Os parâmetros de caminho são partes variáveis ​​de um caminho de URL. Eles geralmente são usados ​​para apontar para um recurso específico dentro de uma coleção.

     Exempo: /orgaos/CELEPAR.


     • Header Parameters
     Esses parâmetros são apresentados no cabeçalho da solicitação e geralmente estão relacionados à autorização, como tokens.

     Exemplo: consumerId: SPIWEB


     • Query Parameters
     Os parâmetros de consulta são o tipo de parâmetro mais comum. Eles aparecem no final do URL de solicitação após um ponto de interrogação. Os parâmetros de consulta podem ser obrigatórios e opcionais.

     Exemplo: /orgaos?ativo=true

     Obs.: Os query parameters devem ser utilizados via de regra para os serviços com método GET. Os demais serviços, devem usar os parâmetros do tipo body parameters.
     Exceto quando o parâmetro não esteja diretamente relacionado com o conteúdo do recurso e sim com a forma de requisição, como o parâmetro assincrono, por exemplo.


     • Body Parameters
     Eles estão incluídos no corpo da solicitação e são usados ​​para enviar e receber dados por meio da API.

     Exemplo: {"codigoOrgao": "CELEPAR", "nomeOrgao": "Companhia de Tecnologia da Informação e Comunicação do Paraná"}

     Obs.: Manter os campos sempre do tipo string, evitar usar campos do tipo inteiros ou do tipo data. Exceto quando for imprescindível a utilização de campo diverso, como o campo binário para o upload de arquivos.
     O retorno dos campos deve sempre ocorrer com campos do tipo string. O nome dos campos do body parameters deve ser camelCase.

• Respostas das requisições

     O retorno das requisições deve ser preferencialmente em formado JSON. Inclusive as mensagens de erro de negócio, devem seguir o mesmo padrão.

     Exemplo: { "message": "Detalhamento da mensagem de erro de negócio" }


     Em alguns casos, quando o serviço somente realiza uma verificação, pode ser retornado apenas um text/plain com o valor do boolean (true ou false).
     No eProtocolo, os serviços com escopo com final ".validar" funcionam desta forma, retornando um boolean em vez de um JSON.



• Códigos de respostas das requisições

     Quando o servidor recebe uma solicitação HTTP, o cliente deve saber o resultado da ação. Se houve sucesso ou falhou. Os códigos de status HTTP são vários códigos padronizados, com várias explicações em vários cenários.
     O servidor sempre deve retornar o código de status correto.

     A seguir estão as categorias dos códigos HTTP:

     • 2xx - Status de sucesso
     • 3xx - Categoria de redirecionamento
     • 4xx - Erro no cliente
     • 5xx - Erro no servidor


     Abaixo uma tabela de quando utilizar cada um dos response status.

     2xx - Status de sucesso

     • 200 Ok -> Retorno que representa sucesso.
     • 201 Created -> Indica que um recurso foi criado. Utilizado para a resposta do POST. Retornar o header Location indicando o GET dessa informação.
     • 202 Accepted -> Indica que o servidor aceitou a request. Utilizado para retorno de requisições assíncronas.
     • 204 No Content -> Representa que a request foi processada com sucesso, mas não há conteúdo para ser retornado.


     3xx - Categoria de redirecionamento

     • 301 Moved Permanently -> Indica que o serviço foi descontinuado e foi movido permanentemente para outra URL. Retornar o header Location indicando o GET do novo serviço.


     4xx - Erro no cliente

     • 400 Bad Request -> Indica que uma condição do serviço não foi satisfeita.
     • 401 Unauthorized -> Indica que o cliente não está autenticado e não tem autorização para acessar o recurso.
     • 403 Forbidden -> Indica que o cliente está autenticado e a requisição é válida. Porém o cliente não tem permissão de acesso naquele recurso.
     • 404 Not Found -> Representa que o recurso não foi localizado.
     • 405 Method Not Allowed -> Indica que o método é diferente do esperado. Por exemplo: o serviço espera o método GET, mas está sendo passado o método POST.
     • 406 Not Acceptable -> Indica que o servidor não pode produzir uma resposta aceitável. Por exemplo, o serviço retorna um text/plain, mas o cliente espera um application/json.
     • 415 Unsupported Media Type -> Representa que o formato do payload não é um formato suportado. Por exemplo, o serviço espera um body parameter, mas ele não é enviado.
     • 429 Too Many Requests -> Indica que a quantidade de requisições simultâneas foi excedida. Tentar novamente mais tarde ou restringir a consulta.


     5xx - Erro no servidor

     • 500 Internal Server Error -> Indica houve uma falha não esperada no servidor e que este não conseguiu processar a requisição. Entrar em contato com o analista do spi-servicos.
     • 503 Service Unavailable -> Indica que o servidor está indisponível. Entrar em contato com a equipe de infraestrutura.
     • 504 Gateway Timeout -> Indica que a requisição excedeu o tempo máximo de espera. Tentar novamente mais tarde, restringir a consulta ou utilizar as requisições assíncronas.