API REST basées sur un script

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 basées sur un script à l’aide du formulaire Service REST scripté disponible sous Services Web basés sur un script → API REST basées sur un script.

Figure 1. Formulaire Service REST scripté

Les vidéos suivantes fournissent des informations supplémentaires sur les API REST scriptées :

• API REST scriptées – Conception
• API REST basées sur un script – Implémentation

URI d’API REST scriptés

Les URI d’API REST scriptés 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 ServiceNow où les utilisateurs accèdent à l’API REST scriptée.
• <name_space>: pour les services Web dans le champ d’application global, l’espace de noms est la valeur de la propriété glide.appcreator.company.code. Pour les services Web dans une application incluse dans le périmètre, l’espace de noms est le nom du périmètre, tel que 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 avec version en spécifiant l’URI sans numéro de version.
• <api_id>: valeur du champ ID d’API sur le formulaire 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 Service REST scripté. Spécifier un chemin d’accès de ressource relative vous permet d’avoir plusieurs ressources utilisant la même méthode HTTP, telle que GET, dans un service Web. Par exemple, une ressource peut spécifier le chemin /{id} lorsque le service Web n’a qu’une seule ressource GET, ou /user/{id} et /message/{id} lorsque le service Web dispose de ressources différentes pour demander des enregistrements d’utilisateur et de message.

Gestion des versions de l’API REST scriptée

Les URI d’API REST scriptés peuvent inclure un numéro de version, par exemple /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 les changements sans impact sur les intégrations existantes.

Version de l’API par défaut

Une version peut être marquée comme valeur par défaut. Spécifier 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 est équivalente à 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 parente. Vous pouvez définir une ou plusieurs ressources par API.

Paramètres de requêtes 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 obligatoires pour chaque demande. Vous pouvez également associer un paramètre de requête à plusieurs ressources.

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

Rôles de l’API REST scriptés

Pour utiliser les API REST basées sur un script, 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 et des ressources de service Web scriptées.

Remarque :

Ces rôles ne sont pas requis pour accéder à un point de terminaison d’API REST 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 valeurs 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 d’API pour contrôler la méthode d’authentification des API. Pour plus d'informations, consultez API access policy.

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

Les listes de contrôle d’accès (ACL) définissent des critères, tels que les rôles requis 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 tous les ACL sélectionnés. Vous pouvez définir une seule ACL pour une API REST entière 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 ayant le rôle snc_external d’effectuer des demandes auprès de 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, reportez-vous aux rubriques 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 scriptées. Utilisez cette table pour identifier la configuration de sécurité de l’API REST scriptée qui convient le mieux à vos besoins, ainsi que 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. L’ACL est requise.	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
Une ACL sélectionnée dans l’enregistrement d’API REST scripté est requise.	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 demande avec un message d’erreur HTTP standard lorsqu’une erreur se produit pendant le traitement de la demande. Vous pouvez utiliser des objets d’erreur dans les ressources d’API REST scriptées pour alerter les clients demandeurs d’erreurs. Utilisez des objets d’erreur pour répondre aux demandes entrantes, et non pour détecter 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 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

Infrastructure 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. Reportez-vous à la section Administration des configurations d’étapes de test REST et des configurations d’étapesde test REST ATF.

Formation pour les développeurs

Dans le , vous ServiceNow® Site Developertrouverez une formation pour les API REST scriptées.

• Créer une API REST scriptée
  Créez une API REST scriptée pour définir des points de terminaison de service web.
• Bonnes pratiques des API REST scriptées
  Suivez ces instructions lors de la conception et de l’implémentation des API REST scriptées.
• Exemples d’API REST scriptées
  Plusieurs exemples sont disponibles pour montrer comment créer et utiliser des API REST scriptées.