DataSnap REST
Remonter à Développement d'applications DataSnap
REST (Representational State Transfer) est l'architecture client-serveur utilisée par le World Wide Web. La conformité aux contraintes REST est référencée comme étant RESTful. Un service web RESTful est implémenté en utilisant HTTP (HyperText Transfer Protocol) et les principes de REST.
Sommaire
Rubriques
- Filtres de requêtes
- JavaScript REST Proxy
- Mise en cache des paramètres DBX
- Rappels avancés REST
- Bibliothèque client REST
- Authentification avec un client JavaScript
- Sessions client JavaScript
- Protocole de messagerie DataSnap REST
Présentation de DataSnap REST
Le protocole REST suppose que le serveur est capable de servir quatre types de requêtes : GET, POST, PUT et DELETE. Ces opérations représentent les opérations de données Récupérer, Mettre à jour, Insérer et Supprimer. Elles sont assimilées aux méthodes serveur via un protocole de mappage. REST suppose que chaque méthode serveur peut être invoquée sous la forme d'une des opérations citées ci-dessus, via un mécanisme de répartition qui suppose un mappage entre le chemin de l'URI (Uniform Resource Identifier), le nom de la méthode et les paramètres.
Mappage des URI
Le serveur répond aux URI. La requête HTTP générale a le format suivant :
http://my.site.com/datasnap/rest/URIClassName/URIMethodName[/inputParameter]*
Le contenu est accepté par les requêtes POST et PUT, assimilées aux requêtes Update et Put. Le protocole par défaut mappe l'URI sur les diverses méthodes serveur, selon le type de commande.
| Type de commande | Modèle de mappage | Exemple |
|---|---|---|
|
|
URICclassName.URIMethodName |
Utility.Storage |
|
|
URIClassName.acceptURIMethodName |
Utility.acceptStorage |
|
|
URIClassName.updateURIMethodName |
Utility.updateStorage |
|
|
URIClassName.cancelURIMethodName |
Utility.cancelStorage |
Selon le type de commande, une requête telle que http://my.site.com/datasnap/rest/utility/storage peut être mappée sur l'une des quatre méthodes ci-dessus. Il est présumé qu'une méthode mappée via une requête GET renvoie l'objet, ou une collection d'objets basée sur les paramètres d'entrée.
Par exemple, une méthode serveur appelée Utility.Storage(Key: String): TJSONValue; correspond à la commande GET :
http://my.site.com/datasnap/rest/utility/storage/test.
Une requête POST invoquera Utility.UpdateStorage(Key: String; Data: TJSONValue);. Le contenu de la requête est mappé sur les données des paramètres d'entrée, le suffixe de l'URI est mappé sur la clé.
Une requête PUT invoquera Utility.AcceptStorage(Key: String; Data: TJSONValue);. La méthode est supposée insérer dans la zone de stockage le paramètre data sous la clé fournie. Le contenu de la requête est mappé sur le second paramètre d'entrée.
Enfin, une requête DELETE invoquera Utility.CancelStorage(Key: String); qui est supposé retirer l'objet de la zone de stockage avec la clé donnée.
Le modèle de mappage peut être redéfini. L'utilisateur peut redéfinir le mappage pour chaque type basé sur les paramètres nom de classe et nom de méthode.
Personnalisation de l'URL pour les requêtes REST
Vous pouvez facilement personnaliser des parties de l'URL pour une requête REST. Vous pouvez changer le contexte DataSnap standard de datasnap/ en mycontext/, par exemple. Vous pouvez aussi changer le contexte REST de rest/ en myrest/, par exemple. Pour ce faire :
- Accédez au WebModule de votre application serveur REST DataSnap.
- Sélectionnez le composant TDSHTTPWebDispatcher.
- Dans l'inspecteur d'objets, localisez la propriété DSContext.
- Remplacez datasnap/ par mycontext/ (ou toute autre valeur requise). N'oubliez pas d'ajouter le / fermant.
- Dans l'inspecteur d'objets, localisez et développez la propriété WebDispatch.
- Modifiez la sous-propriété PathInfo en remplaçant datasnap* par mycontext*.
- Dans l'inspecteur d'objets, localisez la propriété RESTContext.
- Remplacez rest/ par myrest/ (ou toute autre valeur requise). N'oubliez pas d'ajouter le / fermant.
Suite à ces modifications, le serveur DataSnap traitera les requêtes qui commencent par
/mycontext/myrest
au lieu de
/datasnap/rest
Par ailleurs, certaines modifications sont nécessaires pour que les clients utilisent la bonne URL. Ces modifications impliquent de mettre à jour le fichier js\connection.js. Vous devez mettre à jour setConnection comme suit :
function setConnection(host, port, urlPath)
{
connectionInfo = {"host":host,"port":port,"authentication":null,"pathPrefix":urlPath};
connectionInfo.dscontext = 'mycontext';
connectionInfo.restcontext = 'myrest';
}
URI personnalisé pour le mappage de méthode
Depuis RAD Studio 11.0, l'URI REST entrant est associé à une méthode ayant un nom personnalisé (auparavant, un mécanisme automatique dépendant de la méthode HTTP et du nom de la ressource était utilisé).
La nouvelle logique est basée sur un événement TDSMethodMapEvent disponible dans le cadre du composant TDSRESTWebDispatcher et appelé OnNameMap. Lorsque vous avez défini un gestionnaire d'événement pour cet événement, vous pouvez l’utiliser pour définir le nom de la méthode à appeler (paramètre DSMethodName transmis par référence) en fonction du type de requête, du nom de la classe et du nom de la méthode :
procedure TWebModule1.DSRESTWebDispatcher1NameMap(Sender: TObject;
const RequestType, ClassName, MethodName: string; var DSMethodName: string);
begin
end;
Numéros de réponse
Selon l'URI, les méthodes exposées et les résultats de l'exécution, les codes suivants sont renvoyés :
| Code | Raison | Exemple |
|---|---|---|
|
404 |
Le mot clé Datasnap est manquant dans l'URI |
http://my.site.com/rest |
|
501 |
Le mot clé REST (ou un autre protocole) est manquant |
http://my.site.com/datasnap/x/y/z |
|
501 |
Type de commande non reconnu |
Autres commandes que |
|
200 |
Exécution réussie |
La réponse contient les paramètres de sortie {"result":[parameterValue[,parameterValue]*]} |
|
201 |
La requête |
La réponse contient les paramètres de sortie {"result":[parameterValue[,parameterValue]*]} |
|
500 |
L'exécution de la méthode a échoué, la raison est incorporée dans la réponse |
- |
Exposition d'une méthode serveur
Dès que la classe serveur est enregistrée avec le serveur DataSnap, toutes les méthodes doivent être appelables par HTTP si la signature le permet. Si aucun mappage défini par l'utilisateur n'est fourni, les méthodes serveur doivent correspondre à la convention d'affectation des noms afin d'être disponibles pour les requêtes HTTP REST.
Les paramètres sont mappés depuis l'URI immédiatement après le nom de la méthode serveur. Si le nombre de paramètres ne correspond pas, ou s'il ne s'agit pas de paramètres d'entrée ou d'entrée / sortie, une erreur est renvoyée.
Voir aussi
- Bibliothèque client REST
- Expert Application DataSnap REST
- Connexion du client au serveur DataSnap
- RESTful Web Services
- Building Web Services the REST Way
Exemples
- Exemple REST Surf Spot Finder (Delphi)
- Exemple REST Surf Spot Finder (C++)