En REST, comment gérons-nous les différentes façons de renvoyer une collection de ressources?

Question

Nous avons une ressource appelée messages. Nous voulons avoir deux façons de lister sa collection. L'une ne renverrait que les messages obligatoires qui ont été consultés; l'autre, tous les messages. Chacun a des champs qui ne sont pas nécessaires pour l'autre, nous aimerions donc ne pas les renvoyer. Par exemple.

Une réponse devrait ressembler à ceci:

public class MessageListingResponse {
    private Long messageId;
    private String title;
    private String imageUrl;
    private LocalDateTime createdAt;
    private Boolean isViewed;
}

L'autre ressemble à ceci:

public class MandatoryMessageListingResponse {
    private Long messageId;
    private String title;
    private String imageUrl;
    private LocalDateTime createdAt;
    private String description;
}

Je n'ai pas trouvé de règle commune pour ce scénario. Alors, quelle option suit REST?

• /messages/mandatories
• /messages?view=mandatories
• /messages?mandatoryListing=true
• /mandatory-messages

Answer 1

Je n'ai pas pu trouver une règle commune pour ce scénario. Alors, quelle option suit REST?

REST se moque des conventions d'orthographe que vous utilisez pour vos identifiants de ressources.

En particulier, les machines n'importe pas si l'orthographe de l'identifiant correspond ou non à la sémantique de la ressource (rappel : les URL raccourcis fonctionnent)

/messages/obligatoires
/messages?view=mandatories
/messages?mandatoryListing=true
/mandatory-messages

Tous ceux-ci sont bien.

Il y a quelques différences purement mécaniques ; une requête avec des paires clé-valeur est pratique lors de l'utilisation de formulaires HTML en tant que modèles d'URL. Une hiérarchie de chemins est pratique lors de l'utilisation de segments de point et de résolution relative pour décrire d'autres identificateurs dans la même hiérarchie.

Les identifiants en tant que texte apparaissent à plusieurs endroits - nous collons des URI dans les messages, ils sont suivis dans l'historique du navigateur, ils apparaissent dans vos journaux d'accès. Ainsi, nous avons différents humains regardant les identifiants dans différents contextes. Essayez de choisir une orthographe qui est tolérable pour tous, mais optimisez au mieux votre expérience la plus importante.

Answer 2

Ceci est basé sur une opinion mais c'est ainsi que je le ferais. La manière la plus RESTful serait d'utiliser un paramètre de requête, quelque chose comme /messages?view=mandatories. Le problème avec cela (ce n'est peut-être pas un problème pour votre cas d'utilisation, vous devez y réfléchir) est que le modèle de réponse devra être le même que pour /messages, ce qui signifie que vous auriez besoin d'un modèle comme suit (fusion de MessageListingResponse et MandatoryMessageListingResponse):

public class MessageListingResponse {
    private Long messageId;
    private String title;
    private String imageUrl;
    private LocalDateTime createdAt;
    private Boolean isViewed;
    private String description;
}

Si cela n'est pas souhaité (je l'éviterais aussi), alors je choisirais une approche un peu moins RESTful, comme /messages/mandatories. Ce n'est pas si RESTful car les messages sont votre ressource et les informations de chemin suivantes devraient être un ID afin que vous puissiez obtenir un seul message. Une autre possibilité serait quelque chose comme /messages/view:mandatories que je comprends pourrait sembler étrange pour la plupart des gens. Quel que soit la structure que vous utilisez, avec cette approche, vous avez l'avantage d'avoir un modèle spécifique pour cela et ainsi vous pouvez avoir un modèle très spécifique pour chaque point de terminaison, évitant les propriétés qui seraient null dans certains cas et non null dans un autre.

Answer 3

Tout d'abord, s'il s'agit de messages, alors /messages devrait être là car la ressource est un message.

Ensuite, messages/mandatories signifie qu'il y a une liste de messages obligatoires, qui est un sous-ensemble de messages. Si vous avez l'intention d'ajouter ou de mettre à jour un message obligatoire avec put, post ou patch, messages/mandatories est la bonne manière de le faire.

Mais s'il s'agit seulement d'un filtre pour les messages qui sont obligatoires, la meilleure façon de le faire est avec un GET comme ceci : /messages?status=mandatories

Où status est le champ qui indique si le message est obligatoire