REST API : qu'est-ce que c'est, méthodes HTTP et principe de fonctionnement dans les applications mobiles

Qu'est-ce que REST API ?

REST API (API de Transfert d'État Représentationnel) est un style architectural proposé par Roy Fielding dans sa thèse de doctorat en 2000. Il définit un ensemble de contraintes et de principes pour la conception de protocoles réseau. Une API qui respecte ces contraintes est appelée RESTful. REST n'est pas un protocole ou un standard — c'est une approche architecturale qui utilise les protocoles existants (principalement HTTP) pour l'échange de données entre le client et le serveur.

L'idée clé de REST est l'architecture orientée ressources. Au lieu d'appeler des méthodes sur le serveur (comme dans SOAP ou RPC), le client opère sur les ressources : il obtient des listes, en crée de nouvelles, les met à jour ou les supprime. Chaque ressource est une entité du domaine : utilisateur, commande, produit, article. Une ressource a un état qui est transmis au client dans un format standardisé, généralement JSON. Le serveur ne stocke pas l'état du client entre les requêtes — c'est le principe stateless, une exigence clé de REST.

Caractéristiques principales de REST API :

• Stateless — chaque requête du client contient toutes les informations nécessaires à son traitement
• Cacheable — les réponses du serveur doivent être explicitement marquées comme pouvant être mises en cache ou non
• Layered system — l'architecture peut inclure des serveurs intermédiaires, des équilibreurs de charge, des proxies
• Uniform interface — une interface d'interaction unique via les méthodes HTTP, les URL et les codes de statut

Principes de l'architecture REST

REST repose sur six contraintes architecturales formulées par Fielding. Le respect de ces contraintes garantit l'évolutivité, les performances et la facilité d'intégration. Chaque principe résout un problème spécifique des systèmes distribués — de la nécessité de mise en cache aux exigences de sécurité. Examinons chaque principe en détail.

Le principe Uniform Interface comprend en outre quatre sous-contraintes : identification des ressources via URI, manipulation des ressources via des représentations, messages auto-descriptifs et HATEOAS (Hypermedia comme moteur de l'état de l'application). La dernière sous-contrainte est souvent ignorée en pratique — la plupart des API REST modernes n'implémentent pas complètement HATEOAS, ce qui suscite des débats sur le fait qu'une telle API est “vraiment“ RESTful.

Le principe Stateless est l'un des plus importants pour le passage à l'échelle. L'absence de sessions sur le serveur signifie que n'importe quelle instance de serveur peut traiter n'importe quelle requête. Cela simplifie le passage à l'échelle horizontale : il suffit d'ajouter de nouveaux serveurs derrière un équilibreur de charge. Pour les applications mobiles, stateless signifie également qu'une requête peut être envoyée à n'importe quel serveur CDN, ce qui est essentiel pour la disponibilité mondiale.

Méthodes HTTP dans REST

Chaque méthode HTTP dans REST API correspond à une opération spécifique sur une ressource : GET pour la lecture, POST pour la création, PUT pour la mise à jour complète, PATCH pour la mise à jour partielle, DELETE pour la suppression. L'idempotence des méthodes est une caractéristique clé : GET, PUT, DELETE sont idempotents (l'exécution répétée donne le même résultat), POST et PATCH ne le sont pas. Ceci est important pour gérer les erreurs réseau lorsque le client ne sait pas si la requête est arrivée au serveur.

• GET — obtention d'une ressource ou d'une liste de ressources. Idempotent, ne modifie pas l'état du serveur
• POST — création d'une nouvelle ressource. Non idempotent, chaque appel crée une nouvelle ressource
• PUT — remplacement complet d'une ressource. Idempotent, les appels répétés ne modifient pas l'état après le premier
• PATCH — mise à jour partielle d'une ressource. Partiellement idempotent (dépend de l'implémentation)
• DELETE — suppression d'une ressource. Idempotent, la suppression répétée retourne 404, pas une erreur

Les codes de statut HTTP sont une partie intégrante de REST API. Chaque code a une signification spécifique : 200 OK pour un GET réussi, 201 Created pour POST, 204 No Content pour DELETE sans corps de réponse, 400 Bad Request pour des données invalides, 401 Unauthorized pour absence d'authentification, 404 Not Found pour ressource inexistante. L'utilisation correcte des codes de statut rend l'API auto-documentée et simplifie le débogage.

Formats de données : JSON et autres

JSON (JavaScript Object Notation) est le format principal de transfert de données dans REST API. Sa popularité s'explique par sa simplicité, sa lisibilité humaine et son support natif en JavaScript. JSON est transmis avec l'en-tête Content-Type: application/json. Les alternatives incluent XML (verbeux, vieillissant), YAML (pratique pour la configuration, moins courant pour les API) et Protocol Buffers (binaire, efficace pour les systèmes à forte charge).

La structure d'un objet JSON dans REST API comprend généralement les champs id, type et les attributs de la ressource. Pour les collections, un tableau JSON avec des métadonnées de pagination est utilisé. Les API REST modernes suivent la spécification JSON:API (jsonapi.org) ou JSON Schema pour la validation des réponses. L'utilisation d'un format de données unifié simplifie le développement de bibliothèques clientes et la génération de documentation.

Exemple de réponse JSON pour une liste d'utilisateurs :

{
    "data": [
        {
            "id": 1,
            "name": "Anna Petrova",
            "email": "anna@example.com"
        }
    ],
    "meta": {
        "total": 42,
        "page": 1,
        "per_page": 10
    }
}

Le choix du format de transfert de données affecte les performances de l'application mobile. JSON se compresse via GZIP de 70 à 80%, ce qui le rend acceptable pour la plupart des scénarios. Pour les applications en temps réel avec de grands volumes de données (streaming, jeux), il est recommandé de passer à des protocoles binaires ou d'utiliser WebSocket en combinaison avec Protocol Buffers.

Exemples de requêtes REST API

Examinons des exemples pratiques de travail avec REST API côté application mobile. Comme exemple, prenons une API pour travailler avec les commandes dans une boutique en ligne. Pour chaque méthode HTTP, une requête et la réponse attendue du serveur sont présentées. Les exemples montrent la structure typique d'une API RESTful utilisée dans le développement mobile.

GET — obtention d'une liste de commandes

Une requête pour obtenir toutes les commandes d'un utilisateur avec pagination. La réponse contient un tableau d'objets commande et des méta-informations pour la navigation entre les pages. Les paramètres page et per_page sont passés via la query string.

// Interface Retrofit pour REST API
interface OrderApi {
    @GET("api/v1/orders")
    suspend fun getOrders(
        @Query("page") page: Int = 1,
        @Query("per_page") perPage: Int = 20
    ): Response<OrderListResponse>
}

POST — création d'une nouvelle commande

Création d'une nouvelle commande via une requête POST. Le serveur retourne le statut 201 Created et l'objet créé dans le corps de la réponse. Important : la création se fait sur la collection /api/v1/orders, pas sur une ressource spécifique — c'est le modèle RESTful standard.

@POST("api/v1/orders")
suspend fun createOrder(
    @Body order: CreateOrderRequest
): Response<OrderResponse>

// Exemple de corps de requête
data class CreateOrderRequest(
    val productId: String,
    val quantity: Int,
    val addressId: String
)

DELETE — suppression d'une commande

La suppression d'une ressource se fait avec la méthode DELETE sur l'URL spécifique de la commande. La suppression réussie retourne 204 No Content. L'idempotence de DELETE signifie qu'une requête répétée à la même URL retourne 404 Not Found, ce qui est correctement géré côté client.

@DELETE("api/v1/orders/{id}")
suspend fun deleteOrder(
    @Path("id") orderId: String
): Response<Unit>

// Utilisation dans ViewModel
fun removeOrder(orderId: String) {
    viewModelScope.launch {
        val response = api.deleteOrder(orderId)
        if (response.isSuccessful) {
            showSuccess()
        }
    }
}

Ces exemples montrent une implémentation typique de REST API côté Android en utilisant Retrofit et Kotlin Coroutines. Pour les applications iOS, URLSession ou la bibliothèque Alamofire associée aux protocoles Codable jouent un rôle similaire. La structure de REST API reste la même quelle que soit la plateforme — seule la méthode d'exécution des requêtes change.

Conception d'API RESTful : recommandations pratiques

Concevoir une API RESTful de qualité nécessite de suivre des conventions qui rendent l'API intuitive pour les développeurs. Les ressources doivent être nommées avec des noms au pluriel (/users, /orders, /products), les méthodes HTTP doivent refléter les opérations et les URL doivent représenter la hiérarchie d'imbrication. Les erreurs doivent retourner un JSON standardisé avec un code et un message, pas seulement un statut HTTP. Le respect de ces conventions abaisse la barrière d'entrée pour les nouveaux développeurs et simplifie l'intégration.

• Nommage des ressources — pluriel, kebab-case : /api/v1/user-orders, pas /api/v1/getUserOrders
• Filtrage et tri — via des paramètres query : ?status=active&sort=created_at:desc
• Pagination — basée sur curseur pour les grands ensembles, basée sur page pour les petits
• Versionnage — via URL (/api/v2/) ou en-tête Accept-Version
• Erreurs — format unifié : { "error": { "code": "VALIDATION_ERROR", "message": "..." } }
• Limitation de débit — en-têtes X-RateLimit-Remaining et Retry-After

Une erreur courante lors de la conception d'une REST API est l'imbrication excessive des ressources. Au lieu de /users/1/orders/5/items/3, il est préférable d'utiliser une structure plate avec des paramètres query : /items?order_id=5&user_id=1. Cela simplifie la mise en cache, ne nécessite pas de maintenir de longs chemins sur le serveur et est plus facile à documenter. L'architecture plate est également plus compatible avec les requêtes basées sur des graphes lors de la migration vers GraphQL à l'avenir.

La sécurité de REST API est implémentée via l'authentification (JWT, OAuth 2.0) et l'autorisation au niveau des ressources. Chaque requête doit vérifier si l'utilisateur a accès à la ressource demandée. HTTPS est obligatoire — sans chiffrement, les jetons et les données sont transmis en texte clair. Pour les applications mobiles, il est recommandé d'utiliser OAuth 2.0 avec PKCE (Proof Key for Code Exchange) pour l'obtention sécurisée de jetons.

Versionnage et mise en cache

Le versionnage de REST API est nécessaire pour la compatibilité ascendante lors des modifications. Les approches les plus courantes sont : version dans l'URL (/api/v1/orders), version dans l'en-tête (Accept: application/vnd.myapi.v1+json) et version dans le paramètre query (?api_version=1). Le versionnage par URL est la méthode la plus populaire car il est explicitement visible dans les logs et la documentation. Cependant, il viole le principe REST d'une URL unique par ressource.

La mise en cache dans REST API est implémentée via les en-têtes HTTP Cache-Control, ETag et Last-Modified. Les requêtes GET marquées comme pouvant être mises en cache peuvent être servies à partir du cache du navigateur ou du proxy sans contacter le serveur. Pour les applications mobiles, la mise en cache est particulièrement importante — elle réduit la consommation de données et accélère l'affichage des données précédemment chargées en cas de mauvaise connectivité. ETag est un hachage du contenu de la réponse : le client l'envoie dans If-None-Match, et le serveur retourne 304 Not Modified si les données n'ont pas changé.

Les alternatives modernes à REST API incluent GraphQL (récupération flexible de données par le client) et gRPC (protocole binaire sur HTTP/2 pour les microservices). Cependant, REST reste le standard principal pour les API publiques en raison de sa simplicité, de son universalité et de son vaste support d'outils. Le choix entre REST et les alternatives dépend des exigences spécifiques du projet : complexité des requêtes, volume de données, besoins de mise à jour en temps réel.