API REST basées sur un script

  • Rversion finale: Yokohama
  • Mis à jour 30 janv. 2025
  • 6 minutes de lecture

    • La fonctionnalité d’API REST scriptée permet aux développeurs d’applications de créer des API de service Web personnalisées.

    Vous pouvez définir des points de terminaison de service, des paramètres de requête et des en-têtes pour une API REST scriptée, ainsi que des scripts pour gérer la demande et la réponse.

    Les API REST basées sur un script suivent généralement l’architecture REST, mais vous pouvez les personnaliser pour utiliser différentes conventions. Vous définissez des API REST scriptées à l’aide du formulaire Service REST scripté disponible sous Services Web scriptés → API REST basées sur un script.

    Figure 1. Formulaire Service REST scripté
    Formulaire Service REST scripté
    Les vidéos suivantes offrent des informations supplémentaires sur les API REST scriptées :

    URI d’API REST scriptées

    Les URI d’API REST scriptées ont le format suivant :

    https://<instance.service-now.com>/api/<name_space>/<version>/<api_id>/<relative_path>

    Dans cet URI :
    • <instance.service-now.com>: chemin d’accès à l’instance où les ServiceNow utilisateurs accèdent à l’API REST scriptée.
    • <name_space>: pour les services Web dans le périmètre global, l’espace de noms est la valeur de la propriété glide.appcreator.company.code. Pour les services Web d’une application incluse dans le périmètre, l’espace de noms est le nom du périmètre, par exemple x_company_appname. Pour plus d’informations sur les espaces de noms, consultez Périmètre de l’application.
    • <version>:Optionnel. Version du point de terminaison à laquelle accéder si l’API utilise la gestion des versions, telle que v1. Vous pouvez accéder à la version par défaut d’une API versionnée en spécifiant l’URI sans numéro de version.
    • <api_id>: valeur du champ ID d’API sur le formulaire de service REST scripté. Par défaut, cette valeur est basée sur le nom du service.
    • <relative_path>: chemin d’accès relatif défini pour la ressource dans le formulaire de service REST scripté. La spécification d’un chemin de ressource relatif vous permet d’avoir plusieurs ressources à l’aide de la même méthode HTTP, telle que GET, dans un seul service Web. Par exemple, une ressource peut spécifier le chemin d’accès /{id} lorsque le service web n’a qu’une seule ressource GET, ou /user/{id} et /message/{id} lorsque le service web a des ressources différentes pour demander des enregistrements d’utilisateurs et de messages.

    Gestion des versions de l’API REST scriptée

    Les URI de l’API REST scriptées peuvent inclure un numéro de version, tel que /api/management/v1/table/{tableName}. Les numéros de version identifient la version du point de terminaison à laquelle un URI accède. En spécifiant un numéro de version dans vos URI, vous pouvez tester et déployer des changements sans impact sur les intégrations existantes.

    Version d’API par défaut

    Une version peut être marquée comme valeur par défaut. La spécification d’une version par défaut permet aux utilisateurs d’accéder à cette version à l’aide d’un point de terminaison REST scripté sans numéro de version. Si aucune version n’est marquée comme valeur par défaut, la version la plus récente est utilisée comme version par défaut.

    Ressources d’API REST scriptées

    Une ressource d’API REST scriptée équivaut à un point de terminaison REST. Il définit la méthode HTTP à exécuter, le script de traitement et tous les paramètres de remplacement de l’API parent. Vous pouvez définir une ou plusieurs ressources par API.

    Paramètres de requête de l’API REST scriptés

    Les paramètres de requête définissent les valeurs que les utilisateurs demandeurs peuvent transmettre dans une demande. Lors de la création d’une API REST scriptée, vous pouvez spécifier les paramètres disponibles et ceux obligatoires pour chaque demande. Vous pouvez également associer un paramètre de requête à plusieurs ressources.

    Accédez aux paramètres de demande dans des scripts à l’aide du champ queryParams de l’objet de demande.

    Rôles de l’API REST scriptés

    Pour utiliser les API REST scriptées, vous devez disposer du rôle d’administrateur de service web [web_service_admin]. Les utilisateurs disposant de ce rôle peuvent lire, créer, modifier et supprimer des API REST scriptées et des ressources de service Web.
    Remarque :
    Ces rôles ne sont pas requis pour accéder à un point de terminaison REST API scripté.

    Formats de demande et de réponse

    Par défaut, toutes les ressources d'une API prennent en charge les formats de demande et de réponse suivants : application/json, application/xml et texte/xml. Vous pouvez remplacer les formats par défaut au niveau de l’API. Les nouveaux formats s’appliquent à toutes les ressources appartenant à l’API, sauf si une ressource individuelle remplace les paramètres par défaut.

    Sécurité de l’API REST scriptée

    Vous pouvez configurer vos API REST scriptées avec le niveau de sécurité nécessaire. Des API/points de terminaison publics qui ne nécessitent aucune sécurité aux API/points de terminaison hautement sécurisés qui nécessitent une authentification utilisateur avec un contrôle d’accès strict à toutes les ressources.

    Utilisez la fonctionnalité de politique d’accès API pour contrôler la méthode d’authentification des API. Pour plus d'informations, consultez API access policy.

    Contrôles d’accès de l’API REST scriptés

    Les listes de contrôle d’accès (ACL) définissent des critères, tels que les rôles nécessaires et les conditions qu’un utilisateur doit remplir pour accéder à une API REST ou à un point de terminaison scripté. Un utilisateur demandeur doit satisfaire au moins une des ACL. Il n’est pas nécessaire de satisfaire à toutes les ACL sélectionnées. Vous pouvez définir une seule ACL pour toute une API REST ou pour un point de terminaison individuel.

    Remarque :
    Par défaut, les API REST basées sur un script contiennent une ACL qui interdit aux utilisateurs disposant du rôle snc_external d’envoyer des demandes à l’API.

    Lors de la définition d’une ACL d’API REST scriptée, elle doit avoir la valeur TypeREST_Endpoint.

    Pour plus d’informations sur les ACL, consultez Règles de liste de contrôle d’accès et Configurer une ressource d’API REST scriptée pour exiger une ACL.

    Matrice de sécurité de l’API REST scriptée

    Il existe plusieurs configurations de sécurité possibles pour les API REST basées sur un script. Utilisez cette table pour identifier la configuration de sécurité de l’API REST scriptée qui correspond le mieux à vos besoins et les valeurs de champ pour implémenter cette configuration.

    Tableau 1. Sécurité de l’API REST scriptée
    Configuration API REST scriptée Ressource REST scriptée
    ACL par défaut Requiert une authentification Requiert une autorisation d'ACL ACL
    La ressource est publique. Aucune authentification ou ACL n’est requise. N’importe quelle valeur Faux N’importe quelle valeur N’importe quelle valeur
    La ressource nécessite uniquement une authentification de base. Aucune ACL n’est requise. N’importe quelle valeur Vrai Faux N’importe quelle valeur
    La ressource nécessite uniquement une authentification de base. ACL est obligatoire. Aucune ACL sélectionnée Vrai Vrai Aucune ACL sélectionnée
    Une ACL sélectionnée dans l’enregistrement de ressource est requise. N’importe quelle valeur Vrai Vrai Une ou plusieurs ACL sélectionnées
    Un ACL sélectionné dans l’enregistrement scripté de l’API REST est requis. Une ou plusieurs ACL sélectionnées Vrai Vrai Aucune ACL sélectionnée

    Objets d’erreur de l’API REST scriptés

    Les API REST basées sur un script incluent des objets d’erreur qui vous permettent de répondre à une requête avec un message d’erreur HTTP standard lorsqu’une erreur se produit pendant le traitement de la requête. Vous pouvez utiliser des objets d’erreur dans les ressources d’API REST scriptées pour alerter les clients demandeurs des erreurs. Utilisez des objets d’erreur pour répondre aux demandes entrantes, et non pour intercepter les erreurs dans votre code côté serveur.

    Format de réponse d’erreur

    Le type de contenu de la réponse dépend de l’en-tête Accepter de la demande. Si l’en-tête Accepter spécifie un format non pris en charge, tel que image/jpeg, la réponse d’erreur utilise JSON.

    Les réponses d’erreur suivent le format suivant :
    {
  "error": {
    "message": "My error message",
    "detail": "My details"  
  },  
  "status": "failure"
}
    Le code d’état numérique, tel que 404, est inclus dans l’en-tête du code d’état de la réponse, et non dans le corps de la réponse.

    Prise en charge d'Automated Test Framework

    Framework de tests automatisés (ATF) prend en charge les étapes de test REST entrantes. Vous pouvez créer des tests automatisés pour les API REST entrantes personnalisées que vous créez. La création de tests pour vos REST APIs personnalisées simplifie les tests de mise à niveau et permet de vérifier la rétrocompatibilité des modifications apportées à une REST API. Consultez Administration des configurations d’étape de test REST et Configurations d’étape de test REST ATF.

    Formation pour les développeurs

    Dans , ServiceNow® Site Developervous trouverez une formation pour les API REST basées sur un script.