Práticas recomendadas de Scripted REST APIs
Siga estas diretrizes ao projetar e implementar REST APIs de script.
Siga as convenções da REST API
Use padrões de REST API para fornecer uma interface consistente e fácil de usar para os clientes. As convenções de REST API definem um comportamento específico para cada tipo de método. Use as diretrizes a seguir como ponto de partida para projetar sua API.
- GET operações somente consultam dados. Uma solicitação GET nunca deve modificar dados.
- POST As operações do criam novos registros, mas não modificam os registros existentes.
- As operaçõesPUT e PATCH modificam registros existentes.
- DELETE As operações do destroem registros.
Use o controle de versões para controlar as mudanças na sua API
Use o controle de versões para implementar novas funcionalidades e evitar a interrupção das integrações existentes. Ao introduzir mudanças de funcionalidade significativas na sua API, crie uma nova versão da API primeiro. Não introduza um comportamento que interrompa as integrações existentes em uma versão publicada.
O uso do controle de versões permite que você implemente mudanças significativas na API sem interromper os clientes existentes. Você pode liberar a nova versão da API para novos clientes e permitir que os clientes existentes atualizem em seu próprio ritmo.
Incentive os clientes a usar uma API específica de versão ou configure a API sem uma versão padrão para forçar os clientes a especificar uma versão. Você também pode disponibilizar um comportamento novo e opcional adicionando um parâmetro opcional a uma versão existente.
Retornar um código de status HTTP informativo
Retornar um código de status que informe ao solicitante o sucesso ou a falha da solicitação. Retorne um código de status HTTP que ajude o cliente a entender o resultado da solicitação. Use as diretrizes a seguir para códigos de status comuns.
| Código de status | Descrição |
|---|---|
| 200 | Indica que a solicitação foi concluída com sucesso. |
| 201 | Indica que um registro foi criado com sucesso. |
| 204 | Indica que um registro foi excluído com sucesso. |
| 40X (401, 404) | Códigos de status no intervalo 400 indicam um erro do cliente, como 400 para sintaxe de solicitação inválida. |
| 50X (500, 503) | Códigos de status no intervalo 500 indicam que ocorreu um erro no servidor. A solicitação do cliente pode ter sido válida ou inválida, mas ocorreu um problema no servidor que o impediu de processar a solicitação. |
Retornar informações úteis de erro
Forneça ao cliente informações suficientes em mensagens de erro para permitir que ele entenda o problema sem precisar consultar a documentação da API. Uma resposta de erro deve incluir uma mensagem de erro útil, bem como um código de status de erro.
Por exemplo, quando um cliente consulta um registro que não existe, você pode retornar a mensagem de erro "O registro especificado não existe. Certifique-se de que um registro com o ID de<id value> existe na aplicação." junto com um código de status 404.
O recurso de API REST de script inclui vários objetos de erro pré-configurados que você pode usar para erros encontrados com frequência e um objeto de erro ServiceRequest personalizável que você pode usar quando os objetos de erro pré-configurados não atendem às suas necessidades.
Aplicar e testar controles de acesso
Imponha controles de acesso existentes e exija acesso adicional para modificar dados. Além de exigir autenticação para acessar a API, exija autorização para acessar os dados. Use a API GlideRecordSecure em seus scripts de REST API com script. Essa API garante que os controles de acesso definidos nos dados subjacentes sejam aplicados ao usuário solicitante.
Requer controles de acesso adicionais para operações que modificam dados. Solicitações como PUT, POST e DELETE devem exigir um nível de acesso mais alto do que GET. Configure esses recursos de API para exigir uma ACL mais estrita.
Teste seus controles de acesso, autenticação e autorização, antes de liberar a API.
Criar testes para verificar a funcionalidade
Crie testes que verificam a funcionalidade de serviços Web REST de script como parte do processo de desenvolvimento. Use testes repetíveis para garantir que sua API funcione da maneira esperada. O teste também ajuda a garantir que as mudanças feitas não afetem o comportamento esperado da API depois de lançar uma versão. Você pode usar uma aplicação cliente REST que oferece suporte a testes automatizados, como o Postman, para facilitar o teste.
Os testes devem validar o código de resposta, os cabeçalhos e o conteúdo do corpo conforme apropriado para cada recurso implementado. Você também pode usar testes para validar os requisitos de autenticação e para confirmar que os erros retornam respostas úteis.