API REST basées sur un script Bonnes pratiques
Suivez ces instructions lors de la conception et de l’implémentation d’API REST basées sur un script.
Suivre les conventions de REST API
Utilisez les normes de REST API pour fournir une interface cohérente et facile à utiliser aux clients. Les conventions de REST API définissent un comportement spécifique pour chaque type de méthode. Utilisez les directives suivantes comme point de départ pour concevoir votre API.
- GET Les opérations interrogent uniquement les données. Une demande GET ne doit jamais modifier les données.
- POST Les opérations créent de nouveaux enregistrements, mais ne modifient pas les enregistrements existants.
- PUT et PATCH les opérations modifient les enregistrements existants.
- DELETE les opérations détruisent les enregistrements.
Utiliser la gestion des versions pour contrôler les changements apportés à votre API
Utilisez la gestion des versions pour implémenter de nouvelles fonctionnalités et éviter d’interrompre les intégrations existantes. Lorsque vous introduisez des changements de fonctionnalités importants dans votre API, créez d’abord une nouvelle version de l’API. N’introduisez pas de comportement susceptible d’interrompre les intégrations existantes dans une version publiée.
L’utilisation de la gestion des versions vous permet d’implémenter des changements importants dans votre API sans casser les clients existants. Vous pouvez ensuite publier la nouvelle version de l’API pour les nouveaux clients tout en permettant aux clients existants de se mettre à niveau à leur propre rythme.
Encouragez les clients à utiliser une API spécifique à la version ou configurez l’API sans version par défaut pour forcer les clients à spécifier une version. Vous pouvez également rendre disponible un nouveau comportement facultatif en ajoutant un paramètre facultatif à une version existante.
Renvoyer un code d’état HTTP informatif
Renvoie un code d’état qui informe le demandeur de la réussite ou de l’échec de la demande. Renvoie un code d’état HTTP qui aide le client à comprendre le résultat de la demande. Utilisez les instructions suivantes pour les codes d’état courants.
| Code de statut | Description |
|---|---|
| 200 | Indique que la demande a été effectuée avec succès. |
| 201 | Indique qu’un enregistrement a été créé avec succès. |
| 204 | Indique qu’un enregistrement a été supprimé avec succès. |
| 40 fois (401, 404) | Les codes d’état compris dans la plage 400 indiquent une erreur du client, telle que 400 pour une syntaxe de demande non valide. |
| 50X (500, 503) | Les codes d’état de l’ordre de 500 indiquent qu’une erreur du serveur s’est produite. La demande du client peut être valide ou non valide, mais un problème s’est produit sur le serveur qui l’a empêché de traiter la demande. |
Renvoyer des informations utiles sur l’erreur
Fournissez au client suffisamment d’informations dans les messages d’erreur pour lui permettre de comprendre le problème sans avoir à se référer à la documentation de votre API. Une réponse à l’erreur doit inclure un message d’erreur utile, ainsi qu’un code d’état d’erreur.
Par exemple, lorsqu’un client interroge un enregistrement qui n’existe pas, vous pouvez renvoyer le message d’erreur « L’enregistrement spécifié n’existe pas. Vérifiez qu’un enregistrement avec l’ID de < valeur id> existe dans l’application. » ainsi qu’un code d’état 404.
La fonctionnalité d’API REST scriptée comprend plusieurs objets d’erreur préconfigurés que vous pouvez utiliser pour les erreurs couramment rencontrées, ainsi qu’un objet d’erreur ServiceRequest personnalisable que vous pouvez utiliser lorsque les objets d’erreur préconfigurés ne répondent pas à vos besoins.
Appliquer et tester les contrôles d’accès
Appliquez les contrôles d’accès existants et exigez un accès supplémentaire pour modifier les données. En plus d’exiger une authentification pour accéder à l’API, demandez une autorisation pour accéder aux données. Utilisez l’API GlideRecordSecure dans vos scripts API REST scriptés. Cette API garantit que les contrôles d’accès définis sur les données sous-jacentes sont appliqués pour l’utilisateur demandeur.
Demandez des contrôles d’accès supplémentaires pour les opérations qui modifient les données. Les demandes telles que PUT, POST et DELETE doivent nécessiter un niveau d’accès supérieur à celui de GET. Configurez ces ressources d’API pour exiger une ACL plus stricte.
Testez vos contrôles d’accès, à la fois l’authentification et l’autorisation, avant de publier l’API.
Construire des tests pour vérifier les fonctionnalités
Créez des tests qui vérifient les fonctionnalités de vos services Web REST scriptés dans le cadre de votre processus de développement. Utilisez des tests reproductibles pour vous assurer que votre API fonctionne comme vous l’attendez. Les tests permettent également de s’assurer que les modifications apportées n’affectent pas le comportement attendu de l’API après la publication d’une version. Vous pouvez utiliser une application cliente REST qui prend en charge les tests automatisés, telle que Postman, pour faciliter les tests.
Les tests doivent valider le code de réponse, les en-têtes et le contenu du corps comme appropriés pour chaque ressource que vous implémentez. Vous pouvez également utiliser des tests pour valider les exigences d’authentification et confirmer que les erreurs renvoient des réponses utiles.