Web services REST


REST (Representational State Transfer) est un style d’architecture pour les systèmes hypermédia distribués. Il repose sur le protocole HTTP pour accéder à des ressources (grâce à leur URI unique) en utilisant diverses opérations supportées nativement par ce protocole : GET (lecture), POST (écriture), PUT / PATCH (modification), DELETE (suppression).

   Principe de fonctionnement :

1. Un consommateur effectue une demande via une requête à une API REST d'un fournisseur de web services.
2. Le web service REST exécute la requête puis renvoie une réponse au consommateur sous forme d’un flux de données (au format JSON généralement, ce format s’étant imposé au fil des années).
3. Le consommateur utilise la réponse dans le cadre d'une application qu'il a développée.

Product name - ev itsm.png peut être :

  • Fournisseur de web services REST grâce à son API REST : les services proposés sont des fonctionnalités métier au périmètre bien délimité.

    Example documentation icon FR.png  Composant de création ou de suspension d'un incident dans Product name - ev itsm.png

    Dans ce cas, l'application tierce (ex. : une autre application de Service Desk) doit appeler le web service REST Product name - ev itsm.png en passant les valeurs attendues par les paramètres du web service (ex. : numéro de l'incident à suspendre) ; le traitement s'effectue alors comme si Product name - ev itsm.png était actif.
  • Consommateur utilisant des web services REST externes.

    Example documentation icon FR.png  Utilisation, lors d'une étape d'un workflow, d'un composant externe de réinitialisation des mots de passe

    Dans ce cas, le web service REST externe doit être déclaré et configuré dans le menu Administration > REST > Services avant de pouvoir y accéder depuis une étape de processus (via une action REST).

Remarques

  • Le format d'échange de l’API REST Product name - ev itsm.png est JSON.
  • L’API REST Product name - ev itsm.png permet de gérer les ressources ci-dessous.
Ressource Objet JSON Table SQL
assets asset AM_ASSET
catalog-assets catalog-assets AM_CATALOG
catalog-requests catalog-requests SD_CATALOG
configuration-items configuration-items AM_ASSET
departments department AM_DEPARTMENT
employees employee

alias : recipient ; requestor ( * )

AM_EMPLOYEE
known-problems known-problem SD_KNOWN_PROBLEMS
locations location AM_LOCATION
manufacturers manufacturer AM_MANUFACTURER
requests request SD_REQUEST
slas sla SD_SLA
status status SD_STATUS

( * ) L’objet JSON employee dispose de 2 alias utilisés pour la ressource requests afin de gérer le cas des clés étrangères submitted_by et recipient_id de la table SD_REQUEST.

  • Les méthodes (fonctions) PUT et PATCH permettant de modifier une ressource déterminée sont équivalentes.
  • Les méthodes permettant l'accès à une ressource déterminée ou la modification d'une ressource déterminée font appel à un paramètre obligatoire correspondant à un champ de la base de données Product name - ev itsm.png, pour lequel l’unicité est garantie.
        Example documentation icon FR.png  Paramètre asset_id dans les méthodes suivantes :
  • Pour accéder à une ressource déterminée ou modifier une ressource déterminée pour laquelle le système tiers ne connaît pas la valeur du champ utilisé comme paramètre, utilisez la méthode d’accès à une liste en appliquant les options de recherche/filtre souhaitées sur les champs de la base de données. Utilisez ensuite le lien URL (HREF) fourni qui contient l’identifiant unique de chaque ressource.
        Example documentation icon FR.png  Pour accéder à un bien particulier :
    • Utilisez la méthode Voir une liste de biens (GET /assets) avec les options de recherche/filtre possibles sur les champs asset_id, employee_id, location_id, department_id.
    • Le lien URL "HREF": "https://{your_server}/api/v1/{your_account}/assets/27590" vous permet d’accéder au bien dont l'identifiant est 27590.
  • Les résultats (au format JSON) sont retournés dans la langue de l’utilisateur dont le compte est utilisé par accéder à l’API REST Product name - ev itsm.png.

Best Practice big icon.pngBonnes pratiques

  • Pour réaliser vos tests, vous pouvez utiliser :
    • la bibliothèque de requêtes HTTP fournie par Logo - EasyVista.png, qui constitue un ensemble d’exemples pouvant vous aider à comprendre et à utiliser l’API REST Product name - ev itsm.png, et effectuer si besoin des tests sur votre propre environnement Product name - ev itsm.png ;
    • Postman (extension de Chrome), qui est un excellent outil tiers pour industrialiser les tests d’API et notamment d’API REST.

Système de licence et sécurité

  • Toute opération effectuée avec l’API REST Product name - ev itsm.png nécessite un login afin d’accéder à un domaine particulier. À chaque fois qu’un appel vers l’API est effectué, un accès utilisateur est comptabilisé.
  • Pour des raisons de sécurité et afin d’éviter une utilisation indésirable de l’API REST Product name - ev itsm.png par des utilisateurs standard, le champ REST API a été ajouté dans la gestion des profils. Cela permet de définir un profil et un utilisateur dédiés à l'utilisation de l'API -  Open url.png voir Procédure 

Procédures

Comment rechercher et filtrer dans la base de données

Recherche / Filtre par champ

  • Dans les requêtes HTTP, vous pouvez effectuer une recherche/filtre sur un ou plusieurs champs de la base Product name - ev itsm.png en utilisant les noms d’objets correspondants. Toutefois, vous ne pouvez utiliser qu’une seule fois le même objet dans la même requête (l’union n’est pas possible).
    La syntaxe à utiliser est la suivante :
search={(prefix_object_name_1.)object_name_1}:{object_name_value_1}(,{(prefix_object_name_2.)object_name_2}:{object_name_value_2})
  • (prefix_object_name_x.) : Préfixe à indiquer uniquement lorsque l’objet souhaité est contenu dans un autre objet.
  • object_name_x : Nom de l’objet utilisé. Paramètre obligatoire.
  • object_name_value_x : Valeur de l’objet utilisé. Paramètre obligatoire.


         Exemples de requêtes

Correctes
/employees?search=last_name:"Morley, Gaby"

/assets?search=asset_tag:"1012D"
/assets?search=employee.last_name:"Taverner, David"
/assets?search=department.department_en:"Finance"

/requests?search=department.department_en:"Industry"
/requests?search=status.status_en:"Closed"
/requests?search=status.status_en:"In Progress",submit_date_ut:this_week&sort=recipient.last_name+asc
/requests?search=recipient.last_name:"Morley, Gaby"
/requests?search=requestor.last_name:"Morley, Gaby"
/requests?search=recipient.last_name:"Morley, frédérique",status.status_en:"In Progress"
/requests?search=recipient.e_mail:fpachelbel@evtry.com,status.status_en:"Escalated"
/requests?search=recipient.e_mail:adam@evtry.com,status.status_en:"In Progress",submit_date_ut:today
/requests?search=recipient.last_name:"Adam, George",status.status_en:"Closed",submit_date_ut:this_year
/requests?search=recipient.last_name:"Adam, George",status.status_en:"In Progress",submit_date_ut:this_week&sort=submit_date_ut+asc
Incorrectes
/requests?search=recipient.e_mail:adam@evtry.com,morley@evtry.com
/requests?search=recipient.e_mail:adam@evtry.com,recipient.e_mail:morley@evtry.com
/requests?search=recipient.e_mail:adam@evtry.com&morley@evtry.com
/requests?search=recipient.e_mail:adam@evtry.com&recipient.e_mail:morley@evtry.com
  • Vous pouvez utiliser le caractère de substitution * dans vos recherches, en remplaçant le caractère : par le caractère ~ (équivalent à l'instruction SQL LIKE).
    La syntaxe à utiliser est la suivante :
search=object_name~"*value*"

         Example documentation icon FR.png

  • afficher la liste de tous les CI dont le code matériel commence par ZS : ZS_001, ZS_002, ...
              /configuration-items?search=asset_tag~"ZS*"
  • afficher la liste de tous les employés dont le nom de famille commence par Talma : Talma, Karl ; Talma, William ; ...
              /employees?search=last_name~"Talma*"
  • Pour afficher uniquement l'employé dont le nom est Talma, Karl, utilisez le caractère :
              /employees?search=last_name:"Talma, Karl"

Recherche / Filtre par date

Note : Le format de date attendu est celui employé par l’utilisateur de l’API REST Product name - ev itsm.png connecté.

  • Le filtrage par date peut être effectué sur tous les champs de type Date.
  • Les intervalles de dates sont interprétés comme inclusifs.
  • Vous pouvez utiliser des intervalles prédéfinis.

Example documentation icon FR.png

search=SUBMIT_DATE_UT:last_week
search=SUBMIT_DATE_UT:3daysbefore

Liste des valeurs possibles (Note : Non sensibles à la casse) :

  • this_year
  • this_month   
  • this_week
  • this_day / today
  • last_year
  • last_month
  • last_week
  • first_quarter / Q1
  • second_quarter / Q2
  • third_quarter / Q3
  • fourth_quarter / last_quarter/ Q4
  • next_day / tomorrow
  • next_week
  • next_month
  • next_year
  • daysbefore
  • daysafter
  • Vous pouvez utiliser des intervalles explicites.

Example documentation icon FR.png  Du 10/05/2016 au 10/06/2016

search=SUBMIT_DATE_UT:(10/05/2016;10/06/2016) 
Procedure_RESTAPIUser

Comment définir un utilisateur dédié à l'API REST

Étape 1 : Création d'un profil REST API

1. Allez sur l'écran Administration > Gestion des accès > Profils utilisateurs.

2. Créez un nouveau profil -  Open url.png voir Procédure

3. Cochez la case REST API pour lui donner l'autorisation à utiliser l'API REST Product name - ev itsm.png.
         Profile - REST API Users.png

Étape 2 : Création d'un utilisateur dédié, autorisé à effectuer des requêtes REST

1. Allez sur l'annuaire des employés : menu Asset Management / Operation / Transition / Extended CMDB / Projet > Annuaires > Employés.

2. Créez un nouvel employé et attribuez-lui le profil créé précédemment.
         User - Profile REST API.png
Toutes les données multilingues sont retournées dans la langue de cet utilisateur.

EndProcedure_RESTAPIUser

Références API

Accès aux fonctions REST

L'accès se fait via une URL de la forme :  

https://{your_server}/api/v1/{your_account}/{resource_name}
  • {your_server} : URL du serveur
             Example documentation icon FR.png  https://your_company.easyvista.com 
  • {your_account} : Compte Product name - ev itsm.png utilisé
             Example documentation icon FR.png  50004 : Base de production ; 50005 : Base sandbox
  • {resource_name} : Nom de la ressource appelée
             Example documentation icon FR.png  requests ; assets ; employees
     

         Example documentation icon FR.png

https://your_company.easyvista.com/api/v1/50004/employees

Liste des fonctionnalités de l’API REST

Biens

Note : Le terme Biens englobe les matériels / licences / contrats.

Marques

Employés

SLA

Tickets

Note : Le terme Tickets englobe les incidents / demandes (service, changement, investissement) / problèmes / événements.

Entités / Localisations

Éléments de configuration (CI)

Autres

Codes de statut HTTP

StatusHeader
Code Erreur Description
EndStatusHeader
Status200
200 OK (Succès) Requête traitée avec succès.
EndStatus200
Status201
201 Created (Créé) Requête traitée avec succès et création d’un élément.
EndStatus201
Status204
204 Deleted (Supprimé) Requête traitée avec succès et suppression d’un élément.
EndStatus204
Status400
400 Bad Request (Mauvaise requête) Requête formulée de façon incorrecte, qui ne peut pas être exécutée correctement.
Example documentation icon FR.png
{
 "error": "Nothing to update (check fieldnames)"
}
EndStatus400
Status401
401 Unauthorized (Non autorisé) Processus d'authentification pour accéder à la ressource incorrect : Login/Mot de passe incorrect, Session non valide, Compte Product name - ev itsm.png incorrect.
Example documentation icon FR.png
{
 "error": "Invalid Login / Password"
}
EndStatus401
Status403
403 Forbidden (Interdit) Refus d'exécution de la requête par le serveur. À la différence de l'erreur 401, l'authentification est acceptée, mais les droits ne permettent pas au client d'accéder à la ressource : Utilisateur n’ayant pas le paramètre REST API activé dans son profil.
EndStatus403
Status404
404 Not found (Non trouvée) Ressource non trouvée : URI incorrecte, Ressource inexistante, Communication avec le serveur incorrecte, rfc_number non trouvé.
Example documentation icon FR.png
{
 "error": "Resource not found"
}
EndStatus404
Status405
405 Method not allowed (Méthode non autorisée) Méthode de requête non autorisée : non supportée ou pas appropriée pour la ressource.
Example documentation icon FR.png
{
 "error": "Invalid input parameter"
}
EndStatus405
Status406
406 Not acceptable (Inacceptable) Ressource non disponible dans un format respectant les en-têtes Accept de la requête. Note : Le format d'échange de l’API REST Product name - ev itsm.png est JSON.
EndStatus406
Status409
409 Conflict (Conflit) Requête ne pouvant pas être traitée en l’état actuel. Les entrées ne peuvent pas être modifiées ou supprimées.
EndStatus409
Status413
413 Request entity too large (Élément de la requête trop grand) Traitement abandonné dû à une requête trop importante.
EndStatus413
Status500
500 Internal Server Error (Erreur interne du serveur) Message d’erreur générique, donné quand une condition inattendue a été rencontrée et qu'aucun message plus spécifique n’est approprié.
Example documentation icon FR.png
{
 "error": "An error occured. A text message is returned in the body."
}
EndStatus500
Status503
503 Service unavailable (Service non disponible) Service temporairement indisponible ou en maintenance. La requête ne peut pas être traitée.
EndStatus503


ConventionsAPI

Conventions de l'API REST

Convention Signification
Orange Paramètres utilisés dans la chaîne d’une requête HTTP (URL) et qui ne correspondent pas à des champs de la base Product name - ev itsm.png.
Example documentation icon FR.png   Méthode Voir une liste de biens
https://{your_server}/api/v1/{your_account}/assets?max_rows=3&fields=asset_tag
Noir et Gras Paramètres utilisés dans l’URL d’une requête HTTP et qui correspondent à des champs de la base Product name - ev itsm.png.
Example documentation icon FR.png   Méthode Voir un bien
https://{your_server}/api/v1/{your_account}/assets/{asset_id}
Vert Paramètres utilisés dans le corps d’une requête HTTP et qui représentent des noms d’objets JSON correspondant à des champs de la base Product name - ev itsm.png ; ils permettent d’affecter ou de modifier une valeur de champ dans la base.
Example documentation icon FR.png   Méthode Terminer un incident/demande

{  "closed": {  "end_date": "11/20/2016 12:12:12",  }  }
Paramètres utilisés dans le corps d’une requête HTTP et qui représentent des noms d’objets JSON ne correspondant pas à des champs de la base Product name - ev itsm.png.
Example documentation icon FR.png   Méthode Reprendre un incident/demande

{  "restarted": {  "comment": "string (required)"  }  }

Tags:
Modifié par Christine Daussac le 2018/11/14 12:31
Créé par Administrator XWiki le 2016/11/23 10:15

Raccourcis

Recent Updates

Haven't been here in a while? Here's what changed recently:

-   Product name - ev itsm.png
-   Product name - ev sas.png

Interesting Content

How to Automate Integration
Add a Shortcut to an App
History
Quick Dashboard
Full text search - Stop Words

Powered by XWiki ©, EasyVista 2018