Práticas recomendadas de Scripted REST APIs
Siga estas diretrizes ao projetar e implementar REST APIs com script.
Seguir as convenções de REST API
Use os 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 os registros existentes.
- DELETE operações destroem registros.
Use o controle de versões para controlar 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 significativas de funcionalidade na API, crie uma nova versão da API primeiro. Não apresente 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 enquanto permite que os clientes existentes façam upgrade 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
Retorne um código de status que informe ao solicitante sobre 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 de erro úteis
Forneça ao cliente informações suficientes nas 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 REST API com script inclui vários objetos de erro pré-configurados que você pode usar para erros comumente encontrados e um objeto de erro ServiceRequest personalizável que pode ser usado quando os objetos de erro pré-configurados não atenderem às suas necessidades.
Impor 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 dados. Use a API GlideRecordSecure em seus scripts de API REST. Esta API garante que os controles de acesso definidos nos dados subjacentes sejam aplicados para o 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 dos serviços Web REST com script como parte do processo de desenvolvimento. Use testes repetíveis para garantir que sua API funcione da maneira que você espera. O teste também ajuda a garantir que as mudanças feitas não afetem o comportamento esperado da API após o lançamento de uma versão. Você pode usar uma aplicação cliente REST que ofereça suporte a testes automatizados, como o Postman, para facilitar os testes.
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 requisitos de autenticação e para confirmar que os erros retornam respostas úteis.