Bonnes pratiques en matière de Scripted REST APIs
Suivez ces instructions lors de la conception et de l’implémentation d’API REST scriptées.
Suivre les conventions de l’API REST
Utilisez les normes des API REST pour fournir une interface cohérente et facile à utiliser pour les clients. Les conventions de l’API REST définissent un comportement spécifique pour chaque type de méthode. Utilisez les directives suivantes comme point de départ pour la conception de votre API.
- GET Les opérations interrogent uniquement des données. Une requête 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 des 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 de casser 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 qui interromprait les intégrations existantes dans une version publiée.
L’utilisation de la gestion des versions vous permet d’apporter des modifications importantes à votre API sans interrompre les clients existants. Vous pouvez ensuite publier la nouvelle version de l’API pour les nouveaux clients tout en permettant aux clients existants de 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
Renvoyer un code d’état qui informe le demandeur de la réussite ou de l’échec de la demande. Renvoyer un code d’état HTTP qui aide le client à comprendre le résultat de la requête. Utilisez les instructions suivantes pour les codes d’état courants.
| Code d'état | 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. |
| 40X (401 et 404) | Les codes d’état dans la plage 400 indiquent une erreur du client, par exemple 400 pour une syntaxe de requête non valide. |
| 50X (500 et 503) | Les codes d’état dans la plage 500 indiquent qu’une erreur de serveur s’est produite. La demande du client peut être valide ou non valide, mais un problème est survenu sur le serveur et 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 à votre documentation d’API. Une réponse d’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. Assurez-vous qu’un enregistrement avec l’ID de la valeur <id> existe dans l’application. » ainsi qu’un code d’état 404.
La fonctionnalité de l’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, exigez une autorisation pour accéder aux données. Utilisez l’API GlideRecordSecure dans vos scripts d’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 à l’utilisateur demandeur.
Exiger 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, tant pour l’authentification que pour l’autorisation, avant de publier l’API.
Créer des tests pour vérifier la fonctionnalité
Créez des tests qui vérifient la fonctionnalité 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 le souhaitez. Les tests permettent également de s’assurer que les modifications que vous apportez 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 il convient pour chaque ressource que vous implémentez. Vous pouvez également utiliser des tests pour valider les exigences d’authentification et pour confirmer que les erreurs renvoient des réponses utiles.