Qu'est-ce qu'une API SOAP ?

SOAP (Simple Object Access Protocol), c’est un protocole standard pour l’échange de messages XML. Ce langage a été Initialement conçu pour que des applications développées avec différents langages sur différentes plateformes puissent communiquer. Ce protocole est assez ancien, mais lisible par tous les langages. Une requête envoyée à une API SOAP peut être traitée par différents modes de communication : HTTP (pour le web), SMTP (pour les mails), TCP, etc

Tout cela est codifié dans le langage WSDL, c’est un peu comme l’exemple de ce que doit recevoir le serveur. Le WSDL est souvent expliqué comme un contrat entre le fournisseur et le consommateur du service.

Le fait que ce soit un protocole implique que des règles et standards de conformité sont intégrés, notamment sur la sécurité. On l’utilise donc souvent pour des besoins de sécurité.

SOAP possède sa propre gestion d’erreur.

Le langage XML

Le langage XML (Extensible Markup Language) est un langage utilisé principalement pour faciliter les échanges d’informations sur le web. Ce langage de description a pour mission de formaliser des données textuelles, comme le HTML, il utilise un fonctionnement de balise.

Le langage XML se classe dans la catégorie des langages de description (ni un langage de programmation, ni un langage de requêtes).

Le langage WSDL

Le WSDL (Web Services Description Language) est un fichier qui spécifie ce que doit contenir un message de requête et l'apparence du message de réponse, il décrit la fonction d'un service web ainsi que ses limites.

Le WSDL est basé sur le XML ou le schéma XML (XSD). Cela signifie que le WSDL utilise des éléments XML.

SOAP vs REST

On peut se demander quel est le meilleur système à utiliser pour traiter des API. Tout dépend de plusieurs critères :

  • Les besoins
  • Les coûts
  • Le contexte

D’un côté, REST (Representational State Transfer) qui est arrivé plus tard et considéré comme plus rapide est plus souvent utilisé pour les applications web. SOAP qui lui est plus ancien, fait que beaucoup de vieux systèmes reposent dessus.

SOAP reste moins flexible que REST car comme c’est un protocole il possède beaucoup d’exigences, comme les messages sous le format XML. REST lui utilise des formats de message plus légers comme JSON, par exemple.

SOAP est peut-être plus pertinent lorsque l’on veut développer une application sécurisée, qui fait transiter des informations dites « sensibles », par exemple, les systèmes bancaires.

REST peut être plus utile dans un contexte comme le développement d’application mobile, par exemple, lorsqu’il faut des échanges simples et précis. REST est plus léger donc plus adapté aux nouveaux concepts.

Maintenant, nous allons voir comment utiliser une API SOAP dans un contexte précis.

Comment utiliser une API SOAP ?

Initialiser le projet

Tout d'abord, nous allons initialiser notre nouveau projet avec la commande :

dotnet new todoApi

Puis il faudra ajouter le package SoapCore.

dotnet add package SoapCore

Une fois cela fait, on va pouvoir commencer le projet.

Création du modèle

Pour recevoir une requête, il faut obligatoirement un model pour définir à quoi va ressembler l'objet que l'on va récupérer.

Pour cela nous allons créer un dossier Modèles dans lequel nous allons créer le fichier TodoModel.cs

using System.Runtime.Serialization;

using System.Xml.Serialization;

namespace App.Core.Models

{

[DataContract]

[XmlRoot(ElementName = "Todos")]

public class TodoModel
{
[DataMember]
[XmlElement(ElementName = "ID")]
public int Id { get; set; }

[DataMember]
public string? TodoName { get; set; }
[DataMember]
public bool IsDone { get; set; }
}
}

Une fois cela fait, il faut créer un service et son interface pour pouvoir effectuer une requête.

Création service / interface

Ensuite, nous devons créer un service et une interface pour pouvoir créer des méthodes pour utiliser comme on le veux les éléments, que l'on récupère de la requête.

Maintenant, créons un dossier Services et dedans nous allons créer un fichier TodoService.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using System.Xml.Linq;
using SoapApi.Models;

namespace SoapApi.Services
{
public class TodoService : ITodoService
{
public string TodoName(string name)
{
Console.WriteLine(name);
return name;
}

public TodoModel TestTodo(TodoModel todo)
{
return todo;
}

public void XmlMethod(XElement xml)
{
Console.WriteLine(xml.ToString());
}
}
}

Les dépendances codées en dur, comme dans l’exemple précédent, sont problématiques et doivent être évitées pour les raisons suivantes :

  • Pour remplacer TodoService par une implémentation différente, vous devez modifier son instance.
  • Si TodoService a des dépendances, ils doivent également être configurés par son instance. Dans un grand projet comportant plusieurs classes dépendant de TodoService, le code de configuration est éparpillé dans l’application.
  • Cette implémentation complique le test unitaire.

L’injection de dépendances résout ces problèmes via :

  • L’utilisation d’une interface ou classe de base pour extraire l’implémentation des dépendances.
  • Le framework prend la responsabilité de la création d’une instance de la dépendance et de sa suppression lorsqu’elle n’est plus nécessaire.

Nous allons ajouter dans le dossier Service, un fichier pour gérer l’interface, ITodoService.

using System;
using System.Collections.Generic;
using System.Linq;
using System.ServiceModel;
using System.Threading.Tasks;
using SoapApi.Models;

namespace SoapApi.Services
{
[ServiceContract]
public interface ITodoService
{
[OperationContract]
string TodoName (string name);

[OperationContract]
void XmlMethod(System.Xml.Linq.XElement xml);

[OperationContract]
TodoModel TestTodo(TodoModel todo);
}
}

Définition des services

Pour pouvoir utiliser le service que l'on vient de créer, il faut "l'initialiser" dans le fichier Program.cs.

using System;
using System.ServiceModel;
using SoapApi.Services;
using SoapCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSoapCore();
builder.Services.AddSingleton<itodoservice, todoservice="">();
builder.Services.AddSoapExceptionTransformer((ex) => ex.Message);

builder.Services.AddMvc();

var app = builder.Build();

app.Run();

Il faut aussi préciser sur quel lien on va envoyer notre requête, il suffit de rajouter un Endpoint.

app.UseEndpoints(endpoints =>
{
endpoints.UseSoapEndpoint(
"/Todo.asmx",
new SoapEncoderOptions(),
SoapSerializer.XmlSerializer
);
});

Requête à effectuer

La requête que nous allons faire va se faire avec la méthode POST sur l’URL :

Utilisation d'une API SOAP avec .NET Core

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">

<Body>

<ToDoName xmlns="http://tempuri.org:">

<name>faire les courses</name>

</TodoName>

</Body>

</Envelope>

Lorsque la réponse est de ce type :

<Envelope xmlns==http://schemas.xmlsoap.org/soap/envelope/

xmlns:xsd=http://www.w3.org/2001/XMLSchema
xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance >

<s:Body>

<TodoNameResponse xmlns="http://tempuri.org/">

<nameResult>faire les courses</nameResult>

<TodoNameResponse>

<s:Body>

</Envelope>

Et que dans la console on voit s’afficher « faire les courses » c’est que la requête est bien passée et que cette dernière a fonctionné !.

Notre équipe d'experts est à l'écoute de vos besoins et projets d'API ! Rendez vous sur la page Contact