API REST et la livraison d'une ressource binaire

Qu'est-ce que la convention de livrer une ressource binaire (comme un fichier pdf) avec une API REST? Ne vous retournez simplement l'URL de la ressource dans votre JSON ou XML de réponse, par exemple, {"url" : "http://example.com/document.pdf"} ?

J'essaie de comprendre la différence entre un URI et URL et de le garder avec une bonne philosophie. Certes, c'est nouveau pour moi donc je peut-être l'incompréhension de certaines choses.

OriginalL'auteur adamkrell | 2012-08-29

  1. 10

    Cette Section Suppose que Vous Dire: Comment Faire pour indiquer à L'Utilisateur Où Trouver une Ressource Binaire

    La différence entre un URI et URL ne rien avoir à faire avec le binaire vs non-binaire types de données (voir aussi).

    Si vous êtes de retour pour la plupart JSON, puis un url entrée est une voie commune pour aller. Si vous êtes en train de faire quelque chose de plus HTML/XML-ish, alors quelque chose comme un <link> élément avec une bonne rel attribut fait beaucoup de sens.

    Évidemment, si le client effectue une GET demande à l'URL directe vous leur avez donné, alors vous devriez leur envoyer le fichier, sauf si ils ont envoyé un tas de négociation de contenu des en-têtes qui effectivement vous empêcher de remplir leur demande. Dans ce cas, un 406 not Acceptable réponse (ou la définition officielle) fait beaucoup de sens.

    Si tu voulais parler de quelque chose d'autre par votre question, veuillez préciser.

    Une Randonnée "De Faire Comme Ceci" Section

    Première: ignorer URL vs URI. Elle n'a rien à voir avec cela. À tous.

    Suivante: Si votre problème n'est pas "Comment puis-je créer un lien vers une ressource" (susceptible d'être affecté par les choses que je suis sur le point de discuter), mais "Que faire si ma ressource est juste un fichier PDF", vous avez toutes sortes d'options pour y faire face. Tout d'abord, vous avez besoin de prendre du recul et de réfléchir de manière plus abstraite (un peu). Votre ressource est presque certainement pas un "fichier PDF". C'est "un fichier téléchargé par un utilisateur", ou "la version PDF d'un rapport que je génère", etc.

    Dans le premier cas, vous n'avez probablement pas une représentation de la ressource au-delà de la binaire, ils vous a envoyé, ce qui est tout à fait bien. Vous n'aurez probablement pas besoin d'effectuer une sorte de négociation de contenu lorsque vous recevez un GET à l'URL de la ressource. Il suffit de leur envoyer le fichier, sous réserve des mises en garde sur l' 406 je le mentionne ci-dessus.

    Dans le second cas, vous pouvez avoir toutes sortes de représentations de cette ressource: CSV, HTML, LaTeX, you name it. Dans ce cas, lorsque vous recevez un GET à l'URL de la ressource, vous ne devez faire de la négociation de contenu, afin de savoir si leur envoyer le document PDF, ou quelque chose d'autre. Il est possible que vous pourriez avoir une représentation JSON de la ressource qui est juste les premières données que vous utilisez pour générer le fichier PDF.

    Dans les deux cas, il serait inattendu si vous aviez une représentation qui soit strictement des métadonnées sur les ressources. Si nécessaire (souvent il est, parfois, il n'est pas), explicite, des métadonnées externes (par opposition aux métadonnées incorporées à l'intérieur de la ressource binaire, comme l'auteur et le titre de l'info en Pdf) est le plus souvent modélisé comme une ressource distincte.

    Enfin, comme @monitorjbl dit: vous avez probablement ne pas souhaitez intégrer les données binaires directement dans un format de texte comme JSON ou XML. Il y a des façons de le faire, impliquant souvent les mots "base64", mais il n'est généralement pas la meilleure approche. En général, vous ne devriez pas mélanger des données binaires et des données de texte.

    C'est ce que je veux dire, la plupart du temps. Je pourrais juste cracher le pdf quand une requête arrive, mais ça ne semble pas de tout repos. Je suis en supposant que vous ne devez retourner les "représentations" de la ressource plutôt que la ressource elle-même (encore une fois, je suis probablement un malentendu quelque chose ici). C'est pourquoi je suis un peu confus au sujet de l'URI et URL. Votre lien est utile, mais je suis encore à essayer de la préciser.
    J'ai mis à jour ma réponse; j'espère que c'est plus utile, maintenant.
    Je vous remercie. Il y a une représentation des données du format pdf, ce qui est une facture, mais le pdf de données unique (une signature). Je suppose que cela signifie que la meilleure solution est simplement de renvoyer une URL qui pointe vers le fichier pdf? Si oui, alors que l'URL n'est pas considéré comme faisant partie de l'API, correct?
    Ou devrais-je faire la demande GET envoyer un autre en-tête Accept selon que l'utilisateur veut la plaine de données ou le format pdf?
    juste pour s'assurer que je suis clair: vous avez une facture qui peut être affiché dans les "données brutes", ou en format PDF? J'avais pencher vers la négociation de contenu, mais depuis le PDF a une signature (un scan d'une facture papier?) il n'est pas ouvert et se ferme dans mon esprit. Il pourrait être utile de parler avec les personnes qui utiliseront votre service pour voir ce qu'ils préfèrent.

    OriginalL'auteur Hank Gay

  2. 5

    Binaire ou pas, votre REPOS ressources doivent être décrits avec hypermédia types.

    • si votre REPOS clients PUT/POST ressources en msgpack format, le RESTE du serveur peut encore lire ce message et de mettre à jour/créer la ressource. Alors pourquoi pas.
    • si votre REPOS clients PUT/POST ressources en format PDF, ma conjecture est que vous ne serez pas en mesure d'extraire toutes les informations dont vous avez besoin pour créer/mettre à jour une ressource correctement. Donc, pas de.

    Dans ce dernier cas, vous pouvez avoir affaire à un "Google drive"-comme service: ces fichiers Pdf ne sont pas vos ressources en soi, et doit être lié par votre ressource réelle (c'est à dire l'URL doit être à l'intérieur de vos ressources).

    Même si Google Drive peut-être pas l'idéal RESTE de l'API (Référence de l'API), il s'agit de deux JSON ressources réelles et les fichiers binaires.

    +1 pour comment Google Drive API gérer ce

    OriginalL'auteur Brian Clozel

  3. 2

    Dans mon expérience, le faire serait contraire à l'idée d'un REPOS d'un webservice. Vous ne pouvez jamais cache cette réponse sans de graves maux de tête, à la différence traditionnellement services RESTful. Aussi, puisque vous allez avoir à la consommation du service en tant que texte pour lire vos XML/JSON, vous ne serez probablement pas en mesure d'optimiser à la fois le texte et binaire lit. Pour ne pas mentionner, vous devez toujours besoin d'informations binaires, ou si vous voulez prendre un assez important de frapper dans les performances lorsque vous souhaitez uniquement les données de texte. Et si vous toujours besoin de données binaires, peut-être vous demander pourquoi vous avez besoin de la webservice?

    Ce n'est pas à dire qu'il est impossible (il y a BFILS, après tout), ou que le cas d'utilisation de ce est inexistant, mais vous devez être certain que vous ne pouvez pas sortir avec un forçage une demande distincte pour les données binaires avant de tenter de le faire. L'incorporation des données binaires dans un format de document conçu pour le texte est très inefficace, et vos données seront beaucoup plus grandes dans ce formulaire que si c'était juste octets brutes.

    En aparté, si vous êtes toujours en train de faire cela avec un graphique vectoriel des ressources comme SVG, ou certains types de fichiers Pdf, vous pouvez représenter que sous forme de données XML. Encore une fois, vous ne voulez pas, comme l'augmentation de votre charge, mais c'est une option pour obtenir autour de la "besoin binaire" de la chose.

    OriginalL'auteur monitorjbl