REST APIs com script
Siga estas diretrizes ao projetar e implementar REST APIs com 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 da REST API definem um comportamento específico para cada tipo de método. Use as diretrizes a seguir como um ponto de partida para projetar sua API.
- GET dados de consulta somente de operações. Uma solicitação GET nunca deve modificar dados.
- POST as operações criam novos registros, mas não modificam os registros existentes.
- PUTe. PATCHas operações modificam registros existentes.
- DELETE registros de destruição de operações.
Use o controle de versões para controlar mudanças em sua API
Use o controle de versões para implementar novas funcionalidades e evitar interromper integrações existentes. Ao introduzir mudanças de funcionalidade significativas na API, crie uma nova versão da API primeiro. Não introduza comportamento que quebrará as integrações existentes em uma versão publicada.
O controle de versões permite implementar mudanças significativas em sua API sem interromper os clientes existentes. Em seguida, você pode liberar a nova versão da API para novos clientes, permitindo que os clientes existentes façam upgrade no 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 novo comportamento opcional adicionando um parâmetro opcional a uma versão existente.
Retorna um código de status HTTP informativo
Retorna um código de status que informa o solicitante sobre o sucesso ou a falha da solicitação. Retorna um código de status HTTP que ajuda o cliente a entender o resultado da solicitação. Use as diretrizes a seguir para códigos de status comuns.
| Código do 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) | Os códigos de status no intervalo 400 indicam um erro do cliente, como 400 para sintaxe de solicitação inválida. |
| 50X (500, 503) | Os códigos de status no intervalo 500 indicam que ocorreu um erro do 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. |
Retorna informações de erro úteis
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 exista um registro com o ID de <id value> na aplicação." junto com um código de status 404.
O recurso 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 você pode usar quando os objetos de erro pré-configurados não atendem às suas necessidades.
Impor e testar controles de acesso
Impor controles de acesso existentes e exigir acesso adicional para modificar dados. Além de exigir autenticação para acessar a API, exija autorização para acessar os dados. Use GlideRecordSecure API em scripts da REST API com script. Esta API garante que os controles de acesso definidos nos dados subjacentes sejam aplicados ao usuário solicitante.
Controles de acesso adicionais para operações que modificam dados. Solicitações como PUT, POST e DELETE devem exigir um nível de acesso maior 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 com script como parte do processo de desenvolvimento. Use testes repetíveis para garantir que sua API funcione da maneira esperada. Os testes também ajudam 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 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 confirmar se os erros retornam respostas úteis.