From nobody Thu Aug 6 05:33:51 2015 Return-Path: X-Original-To: link-relations@ietfa.amsl.com Delivered-To: link-relations@ietfa.amsl.com Received: from localhost (ietfa.amsl.com [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 021141B2E63 for ; Thu, 6 Aug 2015 05:33:51 -0700 (PDT) X-Virus-Scanned: amavisd-new at amsl.com X-Spam-Flag: NO X-Spam-Score: 0.971 X-Spam-Level: X-Spam-Status: No, score=0.971 tagged_above=-999 required=5 tests=[BAYES_20=-0.001, FM_FORGED_GMAIL=0.622, HELO_EQ_DE=0.35] autolearn=no Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 71ZGy5svO60O for ; Thu, 6 Aug 2015 05:33:49 -0700 (PDT) Received: from mailhost.informatik.uni-bremen.de (mailhost.informatik.uni-bremen.de [IPv6:2001:638:708:30c9::12]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id B628E1B2E62 for ; Thu, 6 Aug 2015 05:33:48 -0700 (PDT) X-Virus-Scanned: amavisd-new at informatik.uni-bremen.de Received: from submithost.informatik.uni-bremen.de (submithost.informatik.uni-bremen.de [IPv6:2001:638:708:30c9::b]) by mailhost.informatik.uni-bremen.de (8.14.5/8.14.5) with ESMTP id t76CXilA029765 for ; Thu, 6 Aug 2015 14:33:44 +0200 (CEST) Received: from mail-wi0-f182.google.com (mail-wi0-f182.google.com [209.85.212.182]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by submithost.informatik.uni-bremen.de (Postfix) with ESMTPSA id 3mn8Ph2dptz4vSv for ; Thu, 6 Aug 2015 14:33:44 +0200 (CEST) Received: by wijp15 with SMTP id p15so20723773wij.0 for ; Thu, 06 Aug 2015 05:33:44 -0700 (PDT) X-Received: by 10.180.219.41 with SMTP id pl9mr6002194wic.30.1438864424068; Thu, 06 Aug 2015 05:33:44 -0700 (PDT) MIME-Version: 1.0 Received: by 10.194.21.201 with HTTP; Thu, 6 Aug 2015 05:33:04 -0700 (PDT) From: Klaus Hartke Date: Thu, 6 Aug 2015 14:33:04 +0200 Message-ID: Subject: Link relation types for non-GET links To: link-relations@ietf.org Content-Type: text/plain; charset=UTF-8 Archived-At: X-BeenThere: link-relations@ietf.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 06 Aug 2015 12:33:51 -0000 Hi link relation type experts, I'm using links in my application to discover resources, and link relation types to indicate the semantics of a link. Now I'm stumbling on links that change the resource state when followed (i.e., links that cause requests with methods other than GET). RFC5988 says that link relation types "can specify the behaviours and properties of the target resource (e.g., allowable HTTP methods, [...])." However, none of the registered link relation types seems to do this. My question is: Have link relation types for non-GET links simply not been registered yet, or should a non-GET link perhaps be a different hypermedia control? For example, let's say I have a collection resource and want to provide a way for clients to add new collection items. So I would add a POST link that, when followed, creates the new item and updates the collection. What should the link relation type be in "http://example.org/collection has a ??? resource at http://example.org/collection"? { "_links": { "terms-of-service": { "href": "http://example.org/tos", "type": "text/html" }, "???": { "href": "http://example.org/collection/" } } } (using HAL-like syntax [1]) Or should I add the equivalent of an HTML form to my media type, and have a "form relation type" (for the lack of a better term) to identify the semantics? This would allow me to make statements of the form "To {relation type} the {context IRI}, make a {method} request to {target IRI}", e.g., "To create-a-new-item-in the http://example.org/collection, make a POST request to http://example.org/collection". { "_links": { "terms-of-service": { "href": "http://example.org/tos", "type": "text/html" }, }, "_forms": { "create-a-new-item-in": { "href": "http://example.org/collection/", "method": "POST", "accept": "application/x-www-form-urlencoded", "fields": [ "firstName", "lastName", "eMail" ] } } } Would it make sense to have a registry for common form relation types? Best regards, Klaus [1] https://tools.ietf.org/html/draft-kelly-json-hal-07 From nobody Thu Aug 6 06:27:54 2015 Return-Path: X-Original-To: link-relations@ietfa.amsl.com Delivered-To: link-relations@ietfa.amsl.com Received: from localhost (ietfa.amsl.com [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 897461B2F59 for ; Thu, 6 Aug 2015 06:27:42 -0700 (PDT) X-Virus-Scanned: amavisd-new at amsl.com X-Spam-Flag: NO X-Spam-Score: -0.087 X-Spam-Level: X-Spam-Status: No, score=-0.087 tagged_above=-999 required=5 tests=[BAYES_05=-0.5, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, FM_FORGED_GMAIL=0.622, FREEMAIL_FROM=0.001, HTML_MESSAGE=0.001, J_CHICKENPOX_38=0.6, RCVD_IN_DNSWL_LOW=-0.7, SPF_PASS=-0.001, T_RP_MATCHES_RCVD=-0.01] autolearn=no Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id S6GhnhgfUGYS for ; Thu, 6 Aug 2015 06:27:41 -0700 (PDT) Received: from nm10-vm0.bullet.mail.ne1.yahoo.com (nm10-vm0.bullet.mail.ne1.yahoo.com [98.138.91.72]) (using TLSv1 with cipher ECDHE-RSA-RC4-SHA (128/128 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 94B5F1B2F58 for ; Thu, 6 Aug 2015 06:27:40 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yahoo.com; s=s2048; t=1438867660; bh=Cw50HziW0OkAxSMizdW/q2NRzqLBb7iEAkohzc3udPE=; h=In-Reply-To:References:From:Date:Subject:To:Cc:From:Subject; b=VDhAoHPdjDlKlkKU0TOpzbZwj07iPs9zsnJopGtZIsJsKOEF9q8vZpyuN1C3kWiqLpOKGkVK4D8sXurJZhbRwyb1Zyz0cDN/wGWwVfjgnL8EnKQISjiTNS0mCvV/hzA+1gUOnIQ15Ji5gca9fvViXtVoyl9Ix+G6rT75RGMF9B8aySK+5VqY5oFzCHEgA3sMyarm9svHzI2DNOm44CXJRfjckjeGgqLuJsYje98dg0V7R4dWYR9YClLGk2sKPkmB6840ygy3i8qfOouR2za+GHvIjexvHM9NwMBE9zlwatnA6V2NHtLMOiRmi8xDemrOB0wd+Cx0gWtCGgzYWuZ+yQ== Received: from [98.138.226.176] by nm10.bullet.mail.ne1.yahoo.com with NNFMP; 06 Aug 2015 13:27:40 -0000 Received: from [98.138.226.56] by tm11.bullet.mail.ne1.yahoo.com with NNFMP; 06 Aug 2015 13:27:40 -0000 Received: from [127.0.0.1] by smtp207.mail.ne1.yahoo.com with NNFMP; 06 Aug 2015 13:27:40 -0000 X-Yahoo-Newman-Id: 169546.70282.bm@smtp207.mail.ne1.yahoo.com X-Yahoo-Newman-Property: ymail-3 X-YMail-OSG: pB.ACb4VM1nE7kWHAQo4NgYTZk57Yy6k4vLlqnj5mXWuUHl N9rVq.7uOWnPLAnp8uJ5gGM7AjdKB1s6Fzre3JBgvJdgARz7Cua030mdOCBR 8cDrVEa6FL1i50R.aKQx3SnloRwlvVcZHyFqlQa6rtgd8HcFv7OfRIE8oCwF FNbixejs4bMAZomrYrSNRejVljax3b.9NQmiA9c8e8q0IIQJrb2GODPxOT.L D2oWXe3A0YfwVDaGEvo0yvQPc6KjxzyyEpsDDFupZdbDpQz6lEh3jah_RmyV Oue69XibJarDD1kJ_..4alnFJ2D9ip7pp074a_mwOkIIigbUAEvK1u6.Bwc7 pYkPlPbb7zovsf7K6_D8GBKQtqn5b1j8RK6E5f8C9Lnbb2q6g34l6LACxZS0 P6.MWS0_kvHbZaUbu8JcAmMiK95gTGfRpQQ1DqHtoMoABD8EcCP.YT0gxLHE txs6G9aPvlKq3iKmIhPs_LvHh2LLlWK9U4cWnHSztygnLCYHFJegrHQvsj2L I7PQY2VGRb7Hy9jIdxqJ_v_cHyuncUA-- X-Yahoo-SMTP: i12ABOmswBAkPG1PnjmsmmFRWA-- Received: by igbpg9 with SMTP id pg9so11195827igb.0 for ; Thu, 06 Aug 2015 06:27:39 -0700 (PDT) X-Gm-Message-State: ALoCoQm4xTCxCvdbs4ohWuGfn45x2Cxm6VrsewyUTX5O9SBsL18mwGWRMD8uwhLlLh3mcSh4Q8Qh X-Received: by 10.50.43.167 with SMTP id x7mr3634600igl.95.1438867659632; Thu, 06 Aug 2015 06:27:39 -0700 (PDT) MIME-Version: 1.0 Received: by 10.79.21.195 with HTTP; Thu, 6 Aug 2015 06:27:20 -0700 (PDT) In-Reply-To: References: From: mike amundsen Date: Thu, 6 Aug 2015 09:27:20 -0400 Message-ID: Subject: Re: Link relation types for non-GET links To: Klaus Hartke Content-Type: multipart/alternative; boundary=089e011602b2bb66f2051ca47bda Archived-At: Cc: link-relations X-BeenThere: link-relations@ietf.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 06 Aug 2015 13:27:42 -0000 --089e011602b2bb66f2051ca47bda Content-Type: text/plain; charset=UTF-8 the IANA reg'd values "edit" and "edit-media" support unsafe (non-GET) actions and are documented in RFC5023[1]. [1] http://tools.ietf.org/html/rfc5023#section-11 mamund +1.859.757.1449 skype: mca.amundsen http://amundsen.com/blog/ http://twitter.com/mamund https://github.com/mamund http://linkedin.com/in/mamund On Thu, Aug 6, 2015 at 8:33 AM, Klaus Hartke wrote: > Hi link relation type experts, > > I'm using links in my application to discover resources, and link > relation types to indicate the semantics of a link. Now I'm stumbling > on links that change the resource state when followed (i.e., links > that cause requests with methods other than GET). > > RFC5988 says that link relation types "can specify the behaviours and > properties of the target resource (e.g., allowable HTTP methods, > [...])." > > However, none of the registered link relation types seems to do this. > My question is: Have link relation types for non-GET links simply not > been registered yet, or should a non-GET link perhaps be a different > hypermedia control? > > For example, let's say I have a collection resource and want to > provide a way for clients to add new collection items. So I would add > a POST link that, when followed, creates the new item and updates the > collection. What should the link relation type be in > "http://example.org/collection has a ??? resource at > http://example.org/collection"? > > { > "_links": { > "terms-of-service": { > "href": "http://example.org/tos", > "type": "text/html" > }, > "???": { > "href": "http://example.org/collection/" > } > } > } > > (using HAL-like syntax [1]) > > Or should I add the equivalent of an HTML form to my media type, and > have a "form relation type" (for the lack of a better term) to > identify the semantics? This would allow me to make statements of the > form "To {relation type} the {context IRI}, make a {method} request to > {target IRI}", e.g., "To create-a-new-item-in the > http://example.org/collection, make a POST request to > http://example.org/collection". > > { > "_links": { > "terms-of-service": { > "href": "http://example.org/tos", > "type": "text/html" > }, > }, > "_forms": { > "create-a-new-item-in": { > "href": "http://example.org/collection/", > "method": "POST", > "accept": "application/x-www-form-urlencoded", > "fields": [ "firstName", "lastName", "eMail" ] > } > } > } > > Would it make sense to have a registry for common form relation types? > > Best regards, > Klaus > > [1] https://tools.ietf.org/html/draft-kelly-json-hal-07 > > _______________________________________________ > link-relations mailing list > link-relations@ietf.org > https://www.ietf.org/mailman/listinfo/link-relations > --089e011602b2bb66f2051ca47bda Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable
the IANA reg'd values "edit" and "edit-= media" support unsafe (non-GET) actions and are documented in RFC5023[= 1].




On Thu, Aug 6, 2015 at 8:33 AM, Klaus Hartke= <= hartke@tzi.org> wrote:
Hi l= ink relation type experts,

I'm using links in my application to discover resources, and link
relation types to indicate the semantics of a link. Now I'm stumbling on links that change the resource state when followed (i.e., links
that cause requests with methods other than GET).

RFC5988 says that link relation types "can specify the behaviours and<= br> properties of the target resource (e.g., allowable HTTP methods,
[...])."

However, none of the registered link relation types seems to do this.
My question is: Have link relation types for non-GET links simply not
been registered yet, or should a non-GET link perhaps be a different
hypermedia control?

For example, let's say I have a collection resource and want to
provide a way for clients to add new collection items. So I would add
a POST link that, when followed, creates the new item and updates the
collection. What should the link relation type be in
"http://example.org/collection has a ??? resource at
http://example.org/collection"?

=C2=A0 {
=C2=A0 =C2=A0 "_links": {
=C2=A0 =C2=A0 =C2=A0 "terms-of-service": {
=C2=A0 =C2=A0 =C2=A0 =C2=A0 "href": "http://example.org/tos= ",
=C2=A0 =C2=A0 =C2=A0 =C2=A0 "type": "text/html"
=C2=A0 =C2=A0 =C2=A0 },
=C2=A0 =C2=A0 =C2=A0 "???": {
=C2=A0 =C2=A0 =C2=A0 =C2=A0 "href": "http://example.org= /collection/"
=C2=A0 =C2=A0 =C2=A0 }
=C2=A0 =C2=A0 }
=C2=A0 }

=C2=A0 (using HAL-like syntax [1])

Or should I add the equivalent of an HTML form to my media type, and
have a "form relation type" (for the lack of a better term) to identify the semantics? This would allow me to make statements of the
form "To {relation type} the {context IRI}, make a {method} request to=
{target IRI}", e.g., "To create-a-new-item-in the
http://example.org/collection, make a POST request to
http://example.org/collection".

=C2=A0 {
=C2=A0 =C2=A0 "_links": {
=C2=A0 =C2=A0 =C2=A0 "terms-of-service": {
=C2=A0 =C2=A0 =C2=A0 =C2=A0 "href": "http://example.org/tos= ",
=C2=A0 =C2=A0 =C2=A0 =C2=A0 "type": "text/html"
=C2=A0 =C2=A0 =C2=A0 },
=C2=A0 =C2=A0 },
=C2=A0 =C2=A0 "_forms": {
=C2=A0 =C2=A0 =C2=A0 "create-a-new-item-in": {
=C2=A0 =C2=A0 =C2=A0 =C2=A0 "href": "http://example.org= /collection/",
=C2=A0 =C2=A0 =C2=A0 =C2=A0 "method": "POST",
=C2=A0 =C2=A0 =C2=A0 =C2=A0 "accept": "application/x-www-for= m-urlencoded",
=C2=A0 =C2=A0 =C2=A0 =C2=A0 "fields": [ "firstName", &q= uot;lastName", "eMail" ]
=C2=A0 =C2=A0 =C2=A0 }
=C2=A0 =C2=A0 }
=C2=A0 }

Would it make sense to have a registry for common form relation types?

Best regards,
Klaus

[1] https://tools.ietf.org/html/draft-kelly-json-= hal-07

_______________________________________________
link-relations mailing list
link-relations@ietf.org
https://www.ietf.org/mailman/listinfo/link-relat= ions

--089e011602b2bb66f2051ca47bda-- From nobody Thu Aug 13 05:03:56 2015 Return-Path: X-Original-To: link-relations@ietfa.amsl.com Delivered-To: link-relations@ietfa.amsl.com Received: from localhost (ietfa.amsl.com [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id F3E551A1A79 for ; Thu, 13 Aug 2015 05:03:54 -0700 (PDT) X-Virus-Scanned: amavisd-new at amsl.com X-Spam-Flag: NO X-Spam-Score: 0.472 X-Spam-Level: X-Spam-Status: No, score=0.472 tagged_above=-999 required=5 tests=[BAYES_05=-0.5, FM_FORGED_GMAIL=0.622, HELO_EQ_DE=0.35] autolearn=no Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id T0JOZmhupqJ9 for ; Thu, 13 Aug 2015 05:03:53 -0700 (PDT) Received: from mailhost.informatik.uni-bremen.de (mailhost.informatik.uni-bremen.de [IPv6:2001:638:708:30c9::12]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 48B961A1A5F for ; Thu, 13 Aug 2015 05:03:53 -0700 (PDT) X-Virus-Scanned: amavisd-new at informatik.uni-bremen.de Received: from submithost.informatik.uni-bremen.de (submithost.informatik.uni-bremen.de [134.102.201.11]) by mailhost.informatik.uni-bremen.de (8.14.5/8.14.5) with ESMTP id t7DC3n0Q008775 for ; Thu, 13 Aug 2015 14:03:49 +0200 (CEST) Received: from mail-wi0-f182.google.com (mail-wi0-f182.google.com [209.85.212.182]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by submithost.informatik.uni-bremen.de (Postfix) with ESMTPSA id 3msRPx4g1qz4vDp for ; Thu, 13 Aug 2015 14:03:49 +0200 (CEST) Received: by wicne3 with SMTP id ne3so256305055wic.1 for ; Thu, 13 Aug 2015 05:03:49 -0700 (PDT) X-Received: by 10.194.184.82 with SMTP id es18mr83047125wjc.79.1439467429282; Thu, 13 Aug 2015 05:03:49 -0700 (PDT) MIME-Version: 1.0 Received: by 10.194.21.201 with HTTP; Thu, 13 Aug 2015 05:03:09 -0700 (PDT) In-Reply-To: References: From: Klaus Hartke Date: Thu, 13 Aug 2015 14:03:09 +0200 Message-ID: Subject: Re: Link relation types for non-GET links To: mike amundsen Content-Type: text/plain; charset=UTF-8 Archived-At: Cc: link-relations X-BeenThere: link-relations@ietf.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 13 Aug 2015 12:03:55 -0000 Mike Amundsen wrote: > the IANA reg'd values "edit" and "edit-media" support unsafe (non-GET) > actions and are documented in RFC5023[1]. So, is that the preferred way of doing things? Would it make sense to register a bunch of generic non-GET link relation types, like "create", "execute", "update", "delete"? It seems the syntax for links in RFC5988 and HAL needs to be extended for non-GET links to include a description of the representation that the service accepts when following the link (e.g., accepted media type and/or a set of form fields). How does a spider distinguish between safe links and unsafe non-GET links? Klaus From nobody Thu Aug 13 05:23:20 2015 Return-Path: X-Original-To: link-relations@ietfa.amsl.com Delivered-To: link-relations@ietfa.amsl.com Received: from localhost (ietfa.amsl.com [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 5F80E1A1ABB for ; Thu, 13 Aug 2015 05:23:18 -0700 (PDT) X-Virus-Scanned: amavisd-new at amsl.com X-Spam-Flag: NO X-Spam-Score: -1.9 X-Spam-Level: X-Spam-Status: No, score=-1.9 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_PASS=-0.001] autolearn=ham Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id A0ny4qSDTpXw for ; Thu, 13 Aug 2015 05:23:16 -0700 (PDT) Received: from mout.gmx.net (mout.gmx.net [212.227.15.19]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 967BC1A1AB8 for ; Thu, 13 Aug 2015 05:23:16 -0700 (PDT) Received: from [192.168.2.177] ([84.187.47.186]) by mail.gmx.com (mrgmx002) with ESMTPSA (Nemesis) id 0MaZWz-1Z6OsR0IfJ-00K5pF; Thu, 13 Aug 2015 14:23:05 +0200 Subject: Re: Link relation types for non-GET links To: Klaus Hartke , mike amundsen References: From: Julian Reschke Message-ID: <55CC8C1D.9060900@gmx.de> Date: Thu, 13 Aug 2015 14:22:53 +0200 User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64; rv:38.0) Gecko/20100101 Thunderbird/38.1.0 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=windows-1252; format=flowed Content-Transfer-Encoding: 7bit X-Provags-ID: V03:K0:BoRqpPJcVLjT2WTvfD4uvX0yFt3L1OSHKTzcruaOFiAIpsjmgYk hefx+BkrkgXA6qXxNCFs64CVzulWeUpDhvtrWg5jA/kyauStwXuK784dePkeNZLxWe4ziuh gc1QGhOh5GG+Ob+RdyVapd+NdJWHSM70pQdva1R0cKQrM9iNS26qIoTRVzUPtZEy68Jphdk VanY3dRQGafCmlI4EOPHw== X-UI-Out-Filterresults: notjunk:1;V01:K0:QtspD0dpDHE=:78cuKv9tG2vmlTUdecfQtN bcFc8qUU/7/qxAyh01GBMh5XloaVLpg8pl603mm5EeM+ACdnmB1Z0oBCHz97NxOmIz+QsKCbM KqIqNDOyjK9FaqSQfocqLUnc+J/apwTO/v7hzEJH7pY7wO6Dh28J7+SXRBO6FRQGYkBNRpSsU 8cv0VbNlMhUhGSXrZXRgtHU+MBJ4hXJHilMSJqRg+5yu48VBpRSzmRSk1Bq38rMmcION/+J+R 0lYIxODvIa7/Ax5SZ+NKfEmadNmmYX3uaxBit0fKcubgCX9wrHzTWFkgZS8AtU+I0bcPh9hL7 l7CKX5taRqr2dYhRm9FOWJCMLQBO6DNcD/oXTYqFJSzswuHF8QDQ/LFu+raGMwEOsdKETzPYA T8D/ohw3FUeXNZanfCMHTKtVf86V7fn/2QjU9D/cGzOqzv6pu//y44/i2EavkV+HYdzjFGVux OPHbBpp5iDff7e+EhOTvvX92tFaM59YKpPft0mAsLg5mIAput4dNsymImIcTtTtUoV6AsjRgZ khGZDDfWGw0UMhCetwnJ0GcgwjgqpXxZBlUkK7G8i1yCzu1KSywtXy563mqSlZTuHX+2v6Jey x9NIfazWdOUKEw3CY9SkP+e7PLwIfwKoEH4QB/cDddMuBRkY5QDWc9uxcczH75M+MoPp+hot3 uu6A0OVA/hsdGrOE4Z/K6MjCW1nryp2P5sWzCxKm9VdiKWwrrOVEixC6+1R8U8wU2Nw6rKyEd oJ+DIDEqMAO5+0JN1HUGT7CYmPGOp6xtlteG/w== Archived-At: Cc: link-relations X-BeenThere: link-relations@ietf.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 13 Aug 2015 12:23:18 -0000 On 2015-08-13 14:03, Klaus Hartke wrote: > Mike Amundsen wrote: >> the IANA reg'd values "edit" and "edit-media" support unsafe (non-GET) >> actions and are documented in RFC5023[1]. > > So, is that the preferred way of doing things? Would it make sense to > register a bunch of generic non-GET link relation types, like > "create", "execute", "update", "delete"? > > It seems the syntax for links in RFC5988 and HAL needs to be extended > for non-GET links to include a description of the representation that > the service accepts when following the link (e.g., accepted media type > and/or a set of form fields). > > How does a spider distinguish between safe links and unsafe non-GET links? A spider is not supposed to use methods other than GET, so how is this a problem? From nobody Thu Aug 13 15:11:18 2015 Return-Path: X-Original-To: link-relations@ietfa.amsl.com Delivered-To: link-relations@ietfa.amsl.com Received: from localhost (ietfa.amsl.com [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 99F761B3B6B for ; Thu, 13 Aug 2015 15:11:17 -0700 (PDT) X-Virus-Scanned: amavisd-new at amsl.com X-Spam-Flag: NO X-Spam-Score: -4.211 X-Spam-Level: X-Spam-Status: No, score=-4.211 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, RCVD_IN_DNSWL_MED=-2.3, SPF_PASS=-0.001, T_RP_MATCHES_RCVD=-0.01] autolearn=ham Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id YueDPWl3tFaK for ; Thu, 13 Aug 2015 15:11:16 -0700 (PDT) Received: from cm02fe.IST.Berkeley.EDU (cm02fe.IST.Berkeley.EDU [169.229.218.143]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 3CFD71B3B6A for ; Thu, 13 Aug 2015 15:11:16 -0700 (PDT) Received: from 205-237-53-216.static.cgocable.ca ([205.237.53.216] helo=dretair11.local) by cm02fe.ist.berkeley.edu with esmtpsa (TLSv1:AES128-SHA:128) (Exim 4.76) (auth plain:dret@berkeley.edu) (envelope-from ) id 1ZQ0iQ-0006fc-7F; Thu, 13 Aug 2015 15:11:15 -0700 Message-ID: <55CD15FF.2060805@berkeley.edu> Date: Thu, 13 Aug 2015 18:11:11 -0400 From: Erik Wilde User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.10; rv:31.0) Gecko/20100101 Thunderbird/31.6.0 MIME-Version: 1.0 To: Klaus Hartke , mike amundsen , link-relations Subject: Re: Link relation types for non-GET links References: In-Reply-To: Content-Type: text/plain; charset=windows-1252; format=flowed Content-Transfer-Encoding: 7bit Archived-At: X-BeenThere: link-relations@ietf.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 13 Aug 2015 22:11:17 -0000 hello klaus. On 2015-08-13 08:03, Klaus Hartke wrote: > Mike Amundsen wrote: >> the IANA reg'd values "edit" and "edit-media" support unsafe (non-GET) >> actions and are documented in RFC5023[1]. > So, is that the preferred way of doing things? Would it make sense to > register a bunch of generic non-GET link relation types, like > "create", "execute", "update", "delete"? not any more than it would make sense to have a generic GET relation type that says "read"... link relation types should primarily indicate why somebody would want to follow a link. in HTTP-land, that may sometime require using methods other than GET, so that the uniform interface is used correctly. if so, the link relation definition (or the service making use of it) should say so, so that clients know how to engage in the interaction. > It seems the syntax for links in RFC5988 and HAL needs to be extended > for non-GET links to include a description of the representation that > the service accepts when following the link (e.g., accepted media type > and/or a set of form fields). that get's rather complicated rather quickly. it has been attempted a couple of times, including by myself... https://github.com/dret/I-D/tree/master/link-desc the problem is where to draw the line, and that is hard to do outside of specific scenarios. for example, for W3C's LDP a simple HTTP header field did the trick (instead of embedding that info into the payload), so that's what they are using: http://www.w3.org/TR/ldp/#header-accept-post but that's quite a bit more limited what you seem to have in mind. however, defining a general-purpose format that captures all possible ways in which link relations may have rules associated with them is hard, and personally, my link description mentioned above draft has stalled because without a better picture of what should and shouldn't be covered, this is a typical "designing into the void" scenario. cheers, dret. -- erik wilde | mailto:dret@berkeley.edu - tel:+1-510-2061079 | | UC Berkeley - School of Information (ISchool) | | http://dret.net/netdret http://twitter.com/dret | From nobody Fri Aug 14 00:07:37 2015 Return-Path: X-Original-To: link-relations@ietfa.amsl.com Delivered-To: link-relations@ietfa.amsl.com Received: from localhost (ietfa.amsl.com [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id A2C1F1A009C for ; Fri, 14 Aug 2015 00:07:36 -0700 (PDT) X-Virus-Scanned: amavisd-new at amsl.com X-Spam-Flag: NO X-Spam-Score: -1.749 X-Spam-Level: X-Spam-Status: No, score=-1.749 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, FREEMAIL_ENVFROM_END_DIGIT=0.25, FREEMAIL_FROM=0.001, HTML_MESSAGE=0.001, SPF_PASS=-0.001] autolearn=no Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id qilC12_yuS5M for ; Fri, 14 Aug 2015 00:07:35 -0700 (PDT) Received: from mail-la0-x234.google.com (mail-la0-x234.google.com [IPv6:2a00:1450:4010:c03::234]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 7CCF61A00A0 for ; Fri, 14 Aug 2015 00:07:34 -0700 (PDT) Received: by lalv9 with SMTP id v9so38800535lal.0 for ; Fri, 14 Aug 2015 00:07:32 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :cc:content-type; bh=sEwU2Pda/D8d1lJHo0mKncRwJCrnFHK6L3n8Bro9s+o=; b=aXshQwDnG/cRVBepjWuLHRZTR0SgwskXkkhRYA8njr5Dpxc7e0p6k30U7hxaX1eNvF MVxbYglbYhN2rUSQ+EigEldRYE0OlVfaFwLWHLg/pbGM66cUtDPxVuS5EmOSIe5CO8BK 8lVdNBXPRK3PeNDo9CjEpGKCrBmhhwJEHYu7VczMadZsASfzRNXS7/+YZpMAKsdjzddv NVpll8ct3T1RW5O0H6hoyfn6016fQLWdCMkZ9yi3BUEZ76Y5EkYfvhRdifMQtax0ZWb4 IEdMiKpv/fQDsMP9NhL8vHXX2DezIDsngQuP1zUWr6baugXlkWjFPJRlRR5WERwKwkht C5ww== MIME-Version: 1.0 X-Received: by 10.152.28.105 with SMTP id a9mr41872447lah.9.1439536052506; Fri, 14 Aug 2015 00:07:32 -0700 (PDT) Received: by 10.112.118.71 with HTTP; Fri, 14 Aug 2015 00:07:31 -0700 (PDT) Received: by 10.112.118.71 with HTTP; Fri, 14 Aug 2015 00:07:31 -0700 (PDT) In-Reply-To: References: Date: Fri, 14 Aug 2015 08:07:31 +0100 Message-ID: Subject: Re: Link relation types for non-GET links From: Mike Kelly To: Klaus Hartke Content-Type: multipart/alternative; boundary=089e0160a2400d2520051d401b69 Archived-At: Cc: link-relations@ietf.org X-BeenThere: link-relations@ietf.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 14 Aug 2015 07:07:36 -0000 --089e0160a2400d2520051d401b69 Content-Type: text/plain; charset=UTF-8 Hi Klaus, You can use a standard HAL link and a link relation if you ensure the link relation is a URL which can be dereferenced to retrieve a machine-readable description of the methods and messages that are possible for that link. Just think of it as machine readable link relation documentation. Cheers, M Sent from my mobile On 6 Aug 2015 13:33, "Klaus Hartke" wrote: > Hi link relation type experts, > > I'm using links in my application to discover resources, and link > relation types to indicate the semantics of a link. Now I'm stumbling > on links that change the resource state when followed (i.e., links > that cause requests with methods other than GET). > > RFC5988 says that link relation types "can specify the behaviours and > properties of the target resource (e.g., allowable HTTP methods, > [...])." > > However, none of the registered link relation types seems to do this. > My question is: Have link relation types for non-GET links simply not > been registered yet, or should a non-GET link perhaps be a different > hypermedia control? > > For example, let's say I have a collection resource and want to > provide a way for clients to add new collection items. So I would add > a POST link that, when followed, creates the new item and updates the > collection. What should the link relation type be in > "http://example.org/collection has a ??? resource at > http://example.org/collection"? > > { > "_links": { > "terms-of-service": { > "href": "http://example.org/tos", > "type": "text/html" > }, > "???": { > "href": "http://example.org/collection/" > } > } > } > > (using HAL-like syntax [1]) > > Or should I add the equivalent of an HTML form to my media type, and > have a "form relation type" (for the lack of a better term) to > identify the semantics? This would allow me to make statements of the > form "To {relation type} the {context IRI}, make a {method} request to > {target IRI}", e.g., "To create-a-new-item-in the > http://example.org/collection, make a POST request to > http://example.org/collection". > > { > "_links": { > "terms-of-service": { > "href": "http://example.org/tos", > "type": "text/html" > }, > }, > "_forms": { > "create-a-new-item-in": { > "href": "http://example.org/collection/", > "method": "POST", > "accept": "application/x-www-form-urlencoded", > "fields": [ "firstName", "lastName", "eMail" ] > } > } > } > > Would it make sense to have a registry for common form relation types? > > Best regards, > Klaus > > [1] https://tools.ietf.org/html/draft-kelly-json-hal-07 > > _______________________________________________ > link-relations mailing list > link-relations@ietf.org > https://www.ietf.org/mailman/listinfo/link-relations > --089e0160a2400d2520051d401b69 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable

Hi Klaus,

You can use a standard HAL link and a link relation if you e= nsure the link relation is a URL which can be dereferenced to retrieve a ma= chine-readable description of the methods and messages that are possible fo= r that link. Just think of it as machine readable link relation documentati= on.

Cheers,
M

Sent from my mobile

On 6 Aug 2015 13:33, "Klaus Hartke" &l= t;hartke@tzi.org> wrote:
Hi link relation type exper= ts,

I'm using links in my application to discover resources, and link
relation types to indicate the semantics of a link. Now I'm stumbling on links that change the resource state when followed (i.e., links
that cause requests with methods other than GET).

RFC5988 says that link relation types "can specify the behaviours and<= br> properties of the target resource (e.g., allowable HTTP methods,
[...])."

However, none of the registered link relation types seems to do this.
My question is: Have link relation types for non-GET links simply not
been registered yet, or should a non-GET link perhaps be a different
hypermedia control?

For example, let's say I have a collection resource and want to
provide a way for clients to add new collection items. So I would add
a POST link that, when followed, creates the new item and updates the
collection. What should the link relation type be in
"http://example.org/collection has a ??? resource at
http://example.org/collection"?

=C2=A0 {
=C2=A0 =C2=A0 "_links": {
=C2=A0 =C2=A0 =C2=A0 "terms-of-service": {
=C2=A0 =C2=A0 =C2=A0 =C2=A0 "href": "http://example.org/tos= ",
=C2=A0 =C2=A0 =C2=A0 =C2=A0 "type": "text/html"
=C2=A0 =C2=A0 =C2=A0 },
=C2=A0 =C2=A0 =C2=A0 "???": {
=C2=A0 =C2=A0 =C2=A0 =C2=A0 "href": "http://example.org= /collection/"
=C2=A0 =C2=A0 =C2=A0 }
=C2=A0 =C2=A0 }
=C2=A0 }

=C2=A0 (using HAL-like syntax [1])

Or should I add the equivalent of an HTML form to my media type, and
have a "form relation type" (for the lack of a better term) to identify the semantics? This would allow me to make statements of the
form "To {relation type} the {context IRI}, make a {method} request to=
{target IRI}", e.g., "To create-a-new-item-in the
http://example.org/collection, make a POST request to
http://example.org/collection".

=C2=A0 {
=C2=A0 =C2=A0 "_links": {
=C2=A0 =C2=A0 =C2=A0 "terms-of-service": {
=C2=A0 =C2=A0 =C2=A0 =C2=A0 "href": "http://example.org/tos= ",
=C2=A0 =C2=A0 =C2=A0 =C2=A0 "type": "text/html"
=C2=A0 =C2=A0 =C2=A0 },
=C2=A0 =C2=A0 },
=C2=A0 =C2=A0 "_forms": {
=C2=A0 =C2=A0 =C2=A0 "create-a-new-item-in": {
=C2=A0 =C2=A0 =C2=A0 =C2=A0 "href": "http://example.org= /collection/",
=C2=A0 =C2=A0 =C2=A0 =C2=A0 "method": "POST",
=C2=A0 =C2=A0 =C2=A0 =C2=A0 "accept": "application/x-www-for= m-urlencoded",
=C2=A0 =C2=A0 =C2=A0 =C2=A0 "fields": [ "firstName", &q= uot;lastName", "eMail" ]
=C2=A0 =C2=A0 =C2=A0 }
=C2=A0 =C2=A0 }
=C2=A0 }

Would it make sense to have a registry for common form relation types?

Best regards,
Klaus

[1] https://tools.ietf.org/html/draft-kelly-json-= hal-07

_______________________________________________
link-relations mailing list
link-relations@ietf.org
https://www.ietf.org/mailman/listinfo/link-relat= ions
--089e0160a2400d2520051d401b69-- From nobody Sat Aug 15 05:17:35 2015 Return-Path: X-Original-To: link-relations@ietfa.amsl.com Delivered-To: link-relations@ietfa.amsl.com Received: from localhost (ietfa.amsl.com [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 231A51A700D for ; Sat, 15 Aug 2015 05:17:34 -0700 (PDT) X-Virus-Scanned: amavisd-new at amsl.com X-Spam-Flag: NO X-Spam-Score: 0.971 X-Spam-Level: X-Spam-Status: No, score=0.971 tagged_above=-999 required=5 tests=[BAYES_20=-0.001, FM_FORGED_GMAIL=0.622, HELO_EQ_DE=0.35] autolearn=no Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 9BMuC-mTkI6v for ; Sat, 15 Aug 2015 05:17:32 -0700 (PDT) Received: from mailhost.informatik.uni-bremen.de (mailhost.informatik.uni-bremen.de [IPv6:2001:638:708:30c9::12]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 868A61A700A for ; Sat, 15 Aug 2015 05:17:32 -0700 (PDT) X-Virus-Scanned: amavisd-new at informatik.uni-bremen.de Received: from submithost.informatik.uni-bremen.de (submithost.informatik.uni-bremen.de [IPv6:2001:638:708:30c9::b]) by mailhost.informatik.uni-bremen.de (8.14.5/8.14.5) with ESMTP id t7FCHTx1011890 for ; Sat, 15 Aug 2015 14:17:29 +0200 (CEST) Received: from mail-ig0-f181.google.com (mail-ig0-f181.google.com [209.85.213.181]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by submithost.informatik.uni-bremen.de (Postfix) with ESMTPSA id 3mtgcn0kgPz4vVd for ; Sat, 15 Aug 2015 14:17:29 +0200 (CEST) Received: by igfj19 with SMTP id j19so29034408igf.0 for ; Sat, 15 Aug 2015 05:17:27 -0700 (PDT) X-Received: by 10.50.60.37 with SMTP id e5mr8299457igr.91.1439641047487; Sat, 15 Aug 2015 05:17:27 -0700 (PDT) MIME-Version: 1.0 Received: by 10.79.39.210 with HTTP; Sat, 15 Aug 2015 05:16:48 -0700 (PDT) In-Reply-To: <55CC8C1D.9060900@gmx.de> References: <55CC8C1D.9060900@gmx.de> From: Klaus Hartke Date: Sat, 15 Aug 2015 14:16:48 +0200 Message-ID: Subject: Re: Link relation types for non-GET links To: Julian Reschke Content-Type: text/plain; charset=UTF-8 Archived-At: Cc: link-relations X-BeenThere: link-relations@ietf.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 15 Aug 2015 12:17:34 -0000 Julian Reschke wrote: >> How does a spider distinguish between safe links and unsafe non-GET links? > > A spider is not supposed to use methods other than GET, so how is this a > problem? If the spider does not know the link relation type, it will assume that there is a safe link between the two resources even when the link relation type defines the link to be unsafe. But maybe that's not a big problem. It's just that HTML defines a number of syntactically different hypermedia controls (, ,
), so a spider can understand whether the link is safe or not even if it does not recognize the link relation type. Klaus From nobody Sat Aug 15 05:21:22 2015 Return-Path: X-Original-To: link-relations@ietfa.amsl.com Delivered-To: link-relations@ietfa.amsl.com Received: from localhost (ietfa.amsl.com [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id ED9C81A87BB for ; Sat, 15 Aug 2015 05:21:21 -0700 (PDT) X-Virus-Scanned: amavisd-new at amsl.com X-Spam-Flag: NO X-Spam-Score: -0.701 X-Spam-Level: X-Spam-Status: No, score=-0.701 tagged_above=-999 required=5 tests=[BAYES_40=-0.001, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_LOW=-0.7, SPF_PASS=-0.001] autolearn=ham Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id o2ozfmRLi9Om for ; Sat, 15 Aug 2015 05:21:20 -0700 (PDT) Received: from mout.gmx.net (mout.gmx.net [212.227.15.19]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 2ECC91A87BA for ; Sat, 15 Aug 2015 05:21:20 -0700 (PDT) Received: from [192.168.2.177] ([84.187.34.52]) by mail.gmx.com (mrgmx002) with ESMTPSA (Nemesis) id 0MePYV-1Z9Kqn0j2l-00Q7xT; Sat, 15 Aug 2015 14:21:18 +0200 Subject: Re: Link relation types for non-GET links To: Klaus Hartke References: <55CC8C1D.9060900@gmx.de> From: Julian Reschke Message-ID: <55CF2EBE.5060203@gmx.de> Date: Sat, 15 Aug 2015 14:21:18 +0200 User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64; rv:38.0) Gecko/20100101 Thunderbird/38.1.0 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit X-Provags-ID: V03:K0:00/8w0CdKDfweoWwFiExydJ6i6nI4TRXkCzrLK6HeCnmKiqT+mg 57WXTCqUUC5RRxZGVwAy5YwdP1OIzGeM3h85qkjrpLxvzdcgOTIduhmJAyILvXT30mNUFqJ uPeH7O6xXgKYJAqy0pkk23b1liC7QmHM0Q+z71gK2X/Di4T5fk8XwpicPyScargPAPtXVfv UGnHd4+IZHgGboPP3pKag== X-UI-Out-Filterresults: notjunk:1;V01:K0:p0MfmfmdSRs=:Krj3S0jd5CQlQ6QVQ8qVdJ Ib4us1WabS5ThdBfqJqlYbxopH4JXCFmUp7i/f2kLemY8Ci2Fpbf+v/QmzlQbOD/E5iLdN7ss hfy8QjGTPcpPPJSfXV3zXotVarNKfYhsinozBedeSZRGr5kgzqQckmmsecl0c12AF5405hIHR 7c1uhftHufrc3SRZTSZ6SQJftk+DPtGCMq2TJyJ0fo51RzLpBCQfxtPyZIXgu+6MVVKYR5u3X H4QYMYqIeFNgjJdMOzoPhf7FBMr2HzQsx3WH69YCpoozpi+jsSJeKphQkNitMBIGidYe+DHHa /wTAy6QdfzQn1hzErXvAcm7VOWl/2uym7QD/YVFHqur3LMDztaFZV8AWckHMA7xhzX4DJyqUB 0th/ESs3MpSk4KYzlS84ND4iwxZ+WWd440F98qEG4bTpfEEpNKxxQKQtf5xShsy7ZxN4UetqO QVe4t9zP9X/nqkP6EKKZ/NJXq6kBjPwzVbS/6xqzO4qiKDmI0moDxflAACqOK2dZliSabzOOE bVf3FIzeAXjslatNRw/zLjzX3z7VE+i8zeWUDR4I6VCjRHFW44aPyEN6MmtrJlIFpVBVmJYzh IPIAzWzKmoH0oFi8vJi49EoRmFYw/BP12vIrPSeREcD6OrJHJWV2pNVWtvhkAt7BXnz5e9TfR DQNmwpR08gIcIifmGn3n3u399IZxIyAkOusnKV3TAc5co5WLF2I/5eNo9eLWLeOeVM12cabpH nEJqWv+DMN9bwZ02KEaXf0npTD2LXshpccovaA== Archived-At: Cc: link-relations X-BeenThere: link-relations@ietf.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 15 Aug 2015 12:21:22 -0000 On 2015-08-15 14:16, Klaus Hartke wrote: > Julian Reschke wrote: >>> How does a spider distinguish between safe links and unsafe non-GET links? >> >> A spider is not supposed to use methods other than GET, so how is this a >> problem? > > If the spider does not know the link relation type, it will assume > that there is a safe link between the two resources even when the link > relation type defines the link to be unsafe. But maybe that's not a > big problem. The link relation by definition can not be "unsafe". > It's just that HTML defines a number of syntactically different > hypermedia controls (, , ), so a spider can understand > whether the link is safe or not even if it does not recognize the link > relation type. The link is always safe; it's the method applied to the link target which might not. Best regards, Julian From nobody Sat Aug 15 05:22:43 2015 Return-Path: X-Original-To: link-relations@ietfa.amsl.com Delivered-To: link-relations@ietfa.amsl.com Received: from localhost (ietfa.amsl.com [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id DE4081A87CA for ; Sat, 15 Aug 2015 05:22:41 -0700 (PDT) X-Virus-Scanned: amavisd-new at amsl.com X-Spam-Flag: NO X-Spam-Score: -0.928 X-Spam-Level: X-Spam-Status: No, score=-0.928 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, FM_FORGED_GMAIL=0.622, HELO_EQ_DE=0.35] autolearn=no Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id Bf1ToZbK3dCG for ; Sat, 15 Aug 2015 05:22:40 -0700 (PDT) Received: from mailhost.informatik.uni-bremen.de (mailhost.informatik.uni-bremen.de [IPv6:2001:638:708:30c9::12]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 4B01E1A87BB for ; Sat, 15 Aug 2015 05:22:40 -0700 (PDT) X-Virus-Scanned: amavisd-new at informatik.uni-bremen.de Received: from submithost.informatik.uni-bremen.de (submithost.informatik.uni-bremen.de [IPv6:2001:638:708:30c9::b]) by mailhost.informatik.uni-bremen.de (8.14.5/8.14.5) with ESMTP id t7FCMaUS024919 for ; Sat, 15 Aug 2015 14:22:36 +0200 (CEST) Received: from mail-ig0-f171.google.com (mail-ig0-f171.google.com [209.85.213.171]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by submithost.informatik.uni-bremen.de (Postfix) with ESMTPSA id 3mtgkh45mKz4vk0 for ; Sat, 15 Aug 2015 14:22:36 +0200 (CEST) Received: by igfj19 with SMTP id j19so29079789igf.0 for ; Sat, 15 Aug 2015 05:22:35 -0700 (PDT) X-Received: by 10.50.25.226 with SMTP id f2mr7967045igg.87.1439641355276; Sat, 15 Aug 2015 05:22:35 -0700 (PDT) MIME-Version: 1.0 Received: by 10.79.39.210 with HTTP; Sat, 15 Aug 2015 05:21:55 -0700 (PDT) In-Reply-To: <55CD15FF.2060805@berkeley.edu> References: <55CD15FF.2060805@berkeley.edu> From: Klaus Hartke Date: Sat, 15 Aug 2015 14:21:55 +0200 Message-ID: Subject: Re: Link relation types for non-GET links To: Erik Wilde Content-Type: text/plain; charset=UTF-8 Archived-At: Cc: link-relations X-BeenThere: link-relations@ietf.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 15 Aug 2015 12:22:42 -0000 Erik Wilde wrote: >> Would it make sense to >> register a bunch of generic non-GET link relation types, like >> "create", "execute", "update", "delete"? > > not any more than it would make sense to have a generic GET relation type > that says "read"... The most common type of links in the web are simple links that could be interpreted as having a "read" relation type. > link relation types should primarily indicate why > somebody would want to follow a link. in HTTP-land, that may sometime > require using methods other than GET, so that the uniform interface is used > correctly. if so, the link relation definition (or the service making use of > it) should say so, so that clients know how to engage in the interaction. Right. For example, if you have a collection resource, you might want to provide a link that, when followed, creates a new item in the collection. Or each item might have links to update or delete the item: Take out the trash. Pick up the kids. Return books to the library. IMO it makes sense to provide one link per action rather than providing a single "edit" link, because some actions might be invalid for the current state of the resource, or the user might not be authorized to perform all actions. > defining a general-purpose format that captures all possible ways in which > link relations may have rules associated with them is hard, and personally, > my link description mentioned above draft has stalled because without a > better picture of what should and shouldn't be covered, this is a typical > "designing into the void" scenario. I'm not trying to design something; I'm trying to collect best practices. However, while safe links seem to be well understood, there does not really seem to be consensus on how hypermedia controls for manipulating resource states should look like. Based on what I've seen so far, to me it seems that such a hypermedia control is modelled best like safe links with the following information: * an identifier identifying the semantics of the hypermedia control (the relation type), * the subject of the hypermedia control (i.e., the resource that is being manipulated, the context), and * enough information for the client to construct a request to manipulate the resource, which includes - the request method to use, - the request URI to use, and - a machine-readable description of the payload to include in the request. So the major difference between a safe link and an unsafe one is the non-GET request method and the description of the payload. I don't think that a lot more than this is needed. (Background: people are looking for advice on how to build applications on top of CoAP [1]. I've started to collect some best practices in a draft [2], and made an attempt at defining some terminology for hypermedia controls [3]. The idea is, if we cannot provide advice for RESTful Web APIs in general, maybe it's possible to establish consensus on how RESTful Web APIs in constrained environments [4] should look like.) Klaus [1] https://tools.ietf.org/html/rfc7252 [2] https://tools.ietf.org/html/draft-hartke-core-apps-01 [3] https://tools.ietf.org/html/draft-hartke-core-apps-01#section-2.4 [4] https://tools.ietf.org/html/rfc7228 From nobody Sat Aug 15 05:28:20 2015 Return-Path: X-Original-To: link-relations@ietfa.amsl.com Delivered-To: link-relations@ietfa.amsl.com Received: from localhost (ietfa.amsl.com [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 2AB991A8823 for ; Sat, 15 Aug 2015 05:28:19 -0700 (PDT) X-Virus-Scanned: amavisd-new at amsl.com X-Spam-Flag: NO X-Spam-Score: -0.928 X-Spam-Level: X-Spam-Status: No, score=-0.928 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, FM_FORGED_GMAIL=0.622, HELO_EQ_DE=0.35] autolearn=no Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id KecSdLhSnIsL for ; Sat, 15 Aug 2015 05:28:18 -0700 (PDT) Received: from mailhost.informatik.uni-bremen.de (mailhost.informatik.uni-bremen.de [IPv6:2001:638:708:30c9::12]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id C3EF41A87ED for ; Sat, 15 Aug 2015 05:28:17 -0700 (PDT) X-Virus-Scanned: amavisd-new at informatik.uni-bremen.de Received: from submithost.informatik.uni-bremen.de (submithost.informatik.uni-bremen.de [134.102.201.11]) by mailhost.informatik.uni-bremen.de (8.14.5/8.14.5) with ESMTP id t7FCSE3v006499 for ; Sat, 15 Aug 2015 14:28:14 +0200 (CEST) Received: from mail-io0-f180.google.com (mail-io0-f180.google.com [209.85.223.180]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by submithost.informatik.uni-bremen.de (Postfix) with ESMTPSA id 3mtgsB2mGrz4vkb for ; Sat, 15 Aug 2015 14:28:14 +0200 (CEST) Received: by iodt126 with SMTP id t126so109628334iod.2 for ; Sat, 15 Aug 2015 05:28:12 -0700 (PDT) X-Received: by 10.107.134.94 with SMTP id i91mr49487894iod.162.1439641692937; Sat, 15 Aug 2015 05:28:12 -0700 (PDT) MIME-Version: 1.0 Received: by 10.79.39.210 with HTTP; Sat, 15 Aug 2015 05:27:33 -0700 (PDT) In-Reply-To: References: From: Klaus Hartke Date: Sat, 15 Aug 2015 14:27:33 +0200 Message-ID: Subject: Re: Link relation types for non-GET links To: Mike Kelly Content-Type: text/plain; charset=UTF-8 Archived-At: Cc: link-relations@ietf.org X-BeenThere: link-relations@ietf.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 15 Aug 2015 12:28:19 -0000 Mike Kelly wrote: > You can use a standard HAL link and a link relation if you ensure the link > relation is a URL which can be dereferenced to retrieve a machine-readable > description of the methods and messages that are possible for that link. > Just think of it as machine readable link relation documentation. That's an interesting idea. It basically adds a level of indirection, which should be useful if many links have the same machine-readable description of possible methods and payloads. However, I think I'd prefer including that description directly at the link, so a client does not have to dereference a URL to understand the link semantics. Klaus From nobody Sat Aug 15 06:03:38 2015 Return-Path: X-Original-To: link-relations@ietfa.amsl.com Delivered-To: link-relations@ietfa.amsl.com Received: from localhost (ietfa.amsl.com [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 84FFF1A8924 for ; Sat, 15 Aug 2015 06:03:37 -0700 (PDT) X-Virus-Scanned: amavisd-new at amsl.com X-Spam-Flag: NO X-Spam-Score: -1.901 X-Spam-Level: X-Spam-Status: No, score=-1.901 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, SPF_PASS=-0.001] autolearn=ham Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id SJlBpOKrx0-z for ; Sat, 15 Aug 2015 06:03:36 -0700 (PDT) Received: from pv33p03im-asmtp001.me.com (pv33p03im-asmtp001.me.com [17.143.180.10]) (using TLSv1.2 with cipher DHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id F10C91A88FD for ; Sat, 15 Aug 2015 06:03:35 -0700 (PDT) Received: from [10.31.33.34] (fw.gkh-setu.de [80.69.33.177]) by pv33p03im-asmtp001.me.com (Oracle Communications Messaging Server 7.0.5.35.0 64bit (built Mar 31 2015)) with ESMTPSA id <0NT400GJZK9J8D10@pv33p03im-asmtp001.me.com> for link-relations@ietf.org; Sat, 15 Aug 2015 13:03:35 +0000 (GMT) Content-type: text/plain; charset=us-ascii MIME-version: 1.0 (Mac OS X Mail 7.3 \(1878.6\)) Subject: Re: Link relation types for non-GET links From: algermissen1971 In-reply-to: <55CF2EBE.5060203@gmx.de> Date: Sat, 15 Aug 2015 15:03:18 +0200 Content-transfer-encoding: quoted-printable Message-id: <562D0D35-70BE-46A3-899D-4A4184F33CC1@icloud.com> References: <55CC8C1D.9060900@gmx.de> <55CF2EBE.5060203@gmx.de> To: Klaus Hartke X-Mailer: Apple Mail (2.1878.6) X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10432:5.14.151,1.0.33,0.0.0000 definitions=2015-08-15_02:2015-08-13,2015-08-15,1970-01-01 signatures=0 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 spamscore=0 suspectscore=0 phishscore=0 adultscore=0 bulkscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=7.0.1-1412110000 definitions=main-1508150151 Archived-At: Cc: Julian Reschke , link-relations X-BeenThere: link-relations@ietf.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 15 Aug 2015 13:03:37 -0000 Klaus, you are trying to mix "resource semantics" with "runtime information". Links (any form of hypermedia for that matter) tell the user agent = whatthe nature of the resource is ("A feed of entries" , "a resource = that supports search", "a product catalog","a product details page", "an = index"..) REST deliberately decouples resource semantics from any runtime = specifics (e.g. which method does a resource support at any given point = in time). The consequence is that a specification of a link relation can = never actuallt constrain meaningfully a server to any specific runtime = behavior. Link relation specs can provide *hints* for implementors what = make sense to support, but these can only ever be just that: hints. The = client must deal with what happens at runtime anyway. Sometimes it can help to provide explicit runtime deatils about the = method (think about HTML forms' "action" attribute), but frankly, = separate syntax constructs (=3D=3Dlink relation types) are usually = better (after all, a resource that supports indexing into (GET form) is = very different from a resource that you can submitt stuff to (POST = form). Ususally (if not allways) you will find that making the supported method = design time information (specs) rather than runtime information seems = necessary at first, but when it comes to putting the method in the = client request code, it will be obvious anyway, which of the handfull of = methods to use. And if the clients sends a PATCH and the server at runtime does not = deliver on whatever promise a spec made - what's the spec going to help? = The client must figure out the method to use from the response headers = anyhow, or apply common sense and retry with the POST ... or give up and = hand the issue to a human for resolution. (REST does not magically solve the contract issues of decentralized = systems, it just prescribes very explicitly the places where they = surface at runetime - do not constrain at design time what makes no = sense to constrain enyway). HTH, Jan On 15 Aug 2015, at 14:21, Julian Reschke wrote: > On 2015-08-15 14:16, Klaus Hartke wrote: >> Julian Reschke wrote: >>>> How does a spider distinguish between safe links and unsafe non-GET = links? >>>=20 >>> A spider is not supposed to use methods other than GET, so how is = this a >>> problem? >>=20 >> If the spider does not know the link relation type, it will assume >> that there is a safe link between the two resources even when the = link >> relation type defines the link to be unsafe. But maybe that's not a >> big problem. >=20 > The link relation by definition can not be "unsafe". >=20 >> It's just that HTML defines a number of syntactically different >> hypermedia controls (, , ), so a spider can understand >> whether the link is safe or not even if it does not recognize the = link >> relation type. >=20 > The link is always safe; it's the method applied to the link target = which might not. >=20 > Best regards, Julian >=20 > _______________________________________________ > link-relations mailing list > link-relations@ietf.org > https://www.ietf.org/mailman/listinfo/link-relations From nobody Sat Aug 15 06:05:35 2015 Return-Path: X-Original-To: link-relations@ietfa.amsl.com Delivered-To: link-relations@ietfa.amsl.com Received: from localhost (ietfa.amsl.com [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 560E41A8997 for ; Sat, 15 Aug 2015 06:05:33 -0700 (PDT) X-Virus-Scanned: amavisd-new at amsl.com X-Spam-Flag: NO X-Spam-Score: -1.749 X-Spam-Level: X-Spam-Status: No, score=-1.749 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, FREEMAIL_ENVFROM_END_DIGIT=0.25, FREEMAIL_FROM=0.001, HTML_MESSAGE=0.001, SPF_PASS=-0.001] autolearn=no Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id QNNWMXa4cELK for ; Sat, 15 Aug 2015 06:05:32 -0700 (PDT) Received: from mail-lb0-x234.google.com (mail-lb0-x234.google.com [IPv6:2a00:1450:4010:c04::234]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id A19A01A895C for ; Sat, 15 Aug 2015 06:05:31 -0700 (PDT) Received: by lbbpu9 with SMTP id pu9so58941019lbb.3 for ; Sat, 15 Aug 2015 06:05:30 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :cc:content-type; bh=B4NJ0fAKxp5pCfsFHKFzfhyPTMXqzCajlq8S2lTo/JA=; b=IEIRP6nHx1v+1RRWCRx/a6z4eZUUHQ29KKxLy4xTcUyFUQ1Gov64n0OIJwoEOL9uRr pvRA0xg4M/vqD0coNCcwA18Mx9orQe1LeFjwUOEif0wvI+ay43EQQF6fqpBu78fP+eCM 9JzapJ6VtdufKgNmJBnDixXzBK0uFqk02AxTC0ovj+g/nbfT9LiTZWZjjVYyldhOcxq5 pi9SyAjYEQM+/XKFM2FXPrPsQQ0TLiB1aM0BA4U5JgPd2O5S+E1kBI1glF01KA9/MO5x UQYRf0R59Xr10dSOGTGqtgEPNjbsL4z9QqTENAT/EqIQvC8oCR6RXqueLfRYtxCo7LZs m4TA== X-Received: by 10.152.2.200 with SMTP id 8mr32516220law.115.1439643930184; Sat, 15 Aug 2015 06:05:30 -0700 (PDT) MIME-Version: 1.0 Received: by 10.112.118.71 with HTTP; Sat, 15 Aug 2015 06:05:10 -0700 (PDT) In-Reply-To: References: From: Mike Kelly Date: Sat, 15 Aug 2015 14:05:10 +0100 Message-ID: Subject: Re: Link relation types for non-GET links To: Klaus Hartke Content-Type: multipart/alternative; boundary=089e0112c2e00fd506051d593967 Archived-At: Cc: link-relations@ietf.org X-BeenThere: link-relations@ietf.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 15 Aug 2015 13:05:33 -0000 --089e0112c2e00fd506051d593967 Content-Type: text/plain; charset=UTF-8 Fair enough. It's worth bearing in mind the cache lifetime of the link rel descriptions are likely to be relatively high compared to the resources themselves; so the indirection could potentially reduce the size of the responses as well as metadata noise in the responses. But if you need/want this information inline, then you can attach it as a properly to the given link object. Cheers, M On Sat, Aug 15, 2015 at 1:27 PM, Klaus Hartke wrote: > Mike Kelly wrote: > > You can use a standard HAL link and a link relation if you ensure the > link > > relation is a URL which can be dereferenced to retrieve a > machine-readable > > description of the methods and messages that are possible for that link. > > Just think of it as machine readable link relation documentation. > > That's an interesting idea. It basically adds a level of indirection, > which should be useful if many links have the same machine-readable > description of possible methods and payloads. However, I think I'd > prefer including that description directly at the link, so a client > does not have to dereference a URL to understand the link semantics. > > Klaus > -- Mike http://twitter.com/mikekelly85 http://github.com/mikekelly http://linkedin.com/in/mikekelly123 --089e0112c2e00fd506051d593967 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable
Fair enough. It's worth bearing in mind the cache life= time of the link rel descriptions are likely to be relatively high compared= to the resources themselves; so the indirection could potentially reduce t= he size of the responses as well as metadata noise in the responses.
But if you need/want this information inline, then you can att= ach it as a properly to the given link object.

Che= ers,
M

On Sat, Aug 15, 2015 at 1:27 PM, Klaus Hartke = <hartke@tzi.org&= gt; wrote:
Mike K= elly wrote:
> You can use a standard HAL link and a link relation if you ensure the = link
> relation is a URL which can be dereferenced to retrieve a machine-read= able
> description of the methods and messages that are possible for that lin= k.
> Just think of it as machine readable link relation documentation.

That's an interesting idea. It basically adds a level of indirec= tion,
which should be useful if many links have the same machine-readable
description of possible methods and payloads. However, I think I'd
prefer including that description directly at the link, so a client
does not have to dereference a URL to understand the link semantics.

Klaus



--
Mike

http://twitter.com/mikekelly85
http://github.com/mikek= elly
http://linkedin.com/in/mikekelly123
--089e0112c2e00fd506051d593967-- From nobody Sat Aug 15 06:53:29 2015 Return-Path: X-Original-To: link-relations@ietfa.amsl.com Delivered-To: link-relations@ietfa.amsl.com Received: from localhost (ietfa.amsl.com [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 2F5DD1B2ECE for ; Sat, 15 Aug 2015 06:53:28 -0700 (PDT) X-Virus-Scanned: amavisd-new at amsl.com X-Spam-Flag: NO X-Spam-Score: -2.312 X-Spam-Level: X-Spam-Status: No, score=-2.312 tagged_above=-999 required=5 tests=[BAYES_20=-0.001, RCVD_IN_DNSWL_MED=-2.3, SPF_PASS=-0.001, T_RP_MATCHES_RCVD=-0.01] autolearn=ham Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id zq5MvF-c35Sp for ; Sat, 15 Aug 2015 06:53:27 -0700 (PDT) Received: from cm02fe.IST.Berkeley.EDU (cm02fe.IST.Berkeley.EDU [169.229.218.143]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 09B4B1B2ECD for ; Sat, 15 Aug 2015 06:53:27 -0700 (PDT) Received: from 205-237-53-208.static.cgocable.ca ([205.237.53.208] helo=dretair11.local) by cm02fe.ist.berkeley.edu with esmtpsa (TLSv1:AES128-SHA:128) (Exim 4.76) (auth plain:dret@berkeley.edu) (envelope-from ) id 1ZQbtl-00067r-7R; Sat, 15 Aug 2015 06:53:26 -0700 Message-ID: <55CF4452.60404@berkeley.edu> Date: Sat, 15 Aug 2015 09:53:22 -0400 From: Erik Wilde User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.10; rv:31.0) Gecko/20100101 Thunderbird/31.6.0 MIME-Version: 1.0 To: link-relations Subject: Re: Link relation types for non-GET links References: <55CC8C1D.9060900@gmx.de> In-Reply-To: Content-Type: text/plain; charset=windows-1252; format=flowed Content-Transfer-Encoding: 7bit Archived-At: X-BeenThere: link-relations@ietf.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 15 Aug 2015 13:53:28 -0000 hello klaus. On 2015-08-15 08:16, Klaus Hartke wrote: > It's just that HTML defines a number of syntactically different > hypermedia controls (, , ), so a spider can understand > whether the link is safe or not even if it does not recognize the link > relation type. http://dret.typepad.com/dretblog/2009/10/links-in-html.html is where just out of curiosity i tried to list all of the link types that are defined by HTML. but keep in mind that from a logical perspective, these are all "link relation types" (except for , which supports and requires runtime typing): each of those elements defines a certain kind of relationship between the HTML page and a referenced resource, and spiders (and other clients) decide based on this relationship whether they want to follow a certain link or not. cheers, dret. -- erik wilde | mailto:dret@berkeley.edu - tel:+1-510-2061079 | | UC Berkeley - School of Information (ISchool) | | http://dret.net/netdret http://twitter.com/dret | From nobody Sat Aug 15 07:09:23 2015 Return-Path: X-Original-To: link-relations@ietfa.amsl.com Delivered-To: link-relations@ietfa.amsl.com Received: from localhost (ietfa.amsl.com [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id CBB181A00ED for ; Sat, 15 Aug 2015 07:09:21 -0700 (PDT) X-Virus-Scanned: amavisd-new at amsl.com X-Spam-Flag: NO X-Spam-Score: -4.211 X-Spam-Level: X-Spam-Status: No, score=-4.211 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, RCVD_IN_DNSWL_MED=-2.3, SPF_PASS=-0.001, T_RP_MATCHES_RCVD=-0.01] autolearn=ham Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id dNRRG24xTlVd for ; Sat, 15 Aug 2015 07:09:19 -0700 (PDT) Received: from cm01fe.IST.Berkeley.EDU (cm01fe.IST.Berkeley.EDU [169.229.218.142]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id CF1F61A00D0 for ; Sat, 15 Aug 2015 07:09:19 -0700 (PDT) Received: from 205-237-53-208.static.cgocable.ca ([205.237.53.208] helo=dretair11.local) by cm01fe.ist.berkeley.edu with esmtpsa (TLSv1:AES128-SHA:128) (Exim 4.76) (auth plain:dret@berkeley.edu) (envelope-from ) id 1ZQc97-0007Co-6N; Sat, 15 Aug 2015 07:09:19 -0700 Message-ID: <55CF480A.3090800@berkeley.edu> Date: Sat, 15 Aug 2015 10:09:14 -0400 From: Erik Wilde User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.10; rv:31.0) Gecko/20100101 Thunderbird/31.6.0 MIME-Version: 1.0 To: link-relations Subject: Re: Link relation types for non-GET links References: <55CD15FF.2060805@berkeley.edu> In-Reply-To: Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit Archived-At: X-BeenThere: link-relations@ietf.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 15 Aug 2015 14:09:22 -0000 hello klaus. On 2015-08-15 08:21, Klaus Hartke wrote: > Erik Wilde wrote: >> not any more than it would make sense to have a generic GET relation type >> that says "read"... > The most common type of links in the web are simple > links that could be interpreted as having a "read" relation type. it's more a relation type: it's an assertion the HTML author is making about the link source. and while none of the "implicit link relation types" (see my previous email) are registered as "explicit IANA link relation types", it still makes a lot of sense to look at them as being their own distinct ways how to interlink resources. > IMO it makes sense to provide one link per action rather than > providing a single "edit" link, because some actions might be invalid > for the current state of the resource, or the user might not be > authorized to perform all actions. i think julian answered the general question well. however, i do agree with you that some designs could benefit from having runtime information. for example, while a general paging link could tell you that you can use a page number as parameter, at runtime it could be nice to let the client know that according to current resource state, there are 42 pages available. the UI then can reflect that. this is the exact reason why https://github.com/dret/I-D/tree/master/link-desc exists: it should allow resources to embed runtime information, so that clients get more information than without it. of course, once the client sends the request, the 42 pages hay now be 41 or 43, and that's still something the client should be prepared to handle. but still, in some scenarios, UI design wants to show that "currently, there are 42 pages", and then runtime info is required. >> defining a general-purpose format that captures all possible ways in which >> link relations may have rules associated with them is hard, and personally, >> my link description mentioned above draft has stalled because without a >> better picture of what should and shouldn't be covered, this is a typical >> "designing into the void" scenario. > I'm not trying to design something; I'm trying to collect best > practices. However, while safe links seem to be well understood, there > does not really seem to be consensus on how hypermedia controls for > manipulating resource states should look like. the reason for this, in my opinion, is that people do this more on an ad-hoc basis. HTML forms are a good example, they do it (allowing GET/POST and defining URI parameter encoding), but in a way that's hard to reuse outside of HTML. https://github.com/dret/I-D/tree/master/link-desc is an attempt to turn this into a reusable model, but like i said in an earlier email, it's not easy to get right because there's a much greater variety of information that people might want to represent than with simple read/GET links. > Based on what I've seen so far, to me it seems that such a hypermedia > control is modelled best like safe links with the following > information: > * an identifier identifying the semantics of the hypermedia control > (the relation type), > * the subject of the hypermedia control (i.e., the resource that is > being manipulated, the context), and > * enough information for the client to construct a request to > manipulate the resource, which includes > - the request method to use, > - the request URI to use, and > - a machine-readable description of the payload to include in > the request. feel free to cross reference this against https://github.com/dret/I-D/tree/master/link-desc. yes, media type would be good (a la Accept-Post), but then also URI template support, but there you also need to add some information about what the variables are supposed to represent. to me, there's a good reason why this has been done ad-hoc and mostly in documented (and not completely machine-readable) form. it's the complexity of the design space. make it too simple and it's not expressive enough. make it expressive enough and it might become too cumbersome for most simpler use cases. > So the major difference between a safe link and an unsafe one is the > non-GET request method and the description of the payload. I don't > think that a lot more than this is needed. what about URI templates? those were very high up in the list of things we needed (see the "page number of paged collection" example above). > (Background: people are looking for advice on how to build > applications on top of CoAP [1]. I've started to collect some best > practices in a draft [2], and made an attempt at defining some > terminology for hypermedia controls [3]. The idea is, if we cannot > provide advice for RESTful Web APIs in general, maybe it's possible to > establish consensus on how RESTful Web APIs in constrained > environments [4] should look like.) > [1] https://tools.ietf.org/html/rfc7252 > [2] https://tools.ietf.org/html/draft-hartke-core-apps-01 > [3] https://tools.ietf.org/html/draft-hartke-core-apps-01#section-2.4 > [4] https://tools.ietf.org/html/rfc7228 interesting. it might be interesting to cross-check [3] with https://github.com/dret/hyperpedia/blob/master/concepts.md, which might have very similar goals. for hyperpedia, i have also started collecting formats (https://github.com/dret/hyperpedia/blob/master/formats.md), but still need to go through that list and see what kind of concepts the individual formats are supporting. do you see anything missing from hyperpedia concepts that you think matters for your scenario? if so, please submit an issue, so that i can make sure that the concepts are as comprehensive as possible. thanks and cheers, dret. -- erik wilde | mailto:dret@berkeley.edu - tel:+1-510-2061079 | | UC Berkeley - School of Information (ISchool) | | http://dret.net/netdret http://twitter.com/dret | From nobody Sat Aug 15 07:13:45 2015 Return-Path: X-Original-To: link-relations@ietfa.amsl.com Delivered-To: link-relations@ietfa.amsl.com Received: from localhost (ietfa.amsl.com [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 205611A00ED for ; Sat, 15 Aug 2015 07:13:43 -0700 (PDT) X-Virus-Scanned: amavisd-new at amsl.com X-Spam-Flag: NO X-Spam-Score: -4.211 X-Spam-Level: X-Spam-Status: No, score=-4.211 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, RCVD_IN_DNSWL_MED=-2.3, SPF_PASS=-0.001, T_RP_MATCHES_RCVD=-0.01] autolearn=ham Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id tsUcxVUqF4z4 for ; Sat, 15 Aug 2015 07:13:41 -0700 (PDT) Received: from cm03fe.IST.Berkeley.EDU (cm03fe.IST.Berkeley.EDU [169.229.218.144]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id ADFBF1A00E2 for ; Sat, 15 Aug 2015 07:13:41 -0700 (PDT) Received: from 205-237-53-208.static.cgocable.ca ([205.237.53.208] helo=dretair11.local) by cm03fe.ist.berkeley.edu with esmtpsa (TLSv1:AES128-SHA:128) (Exim 4.76) (auth plain:dret@berkeley.edu) (envelope-from ) id 1ZQcDL-0005aY-Bn; Sat, 15 Aug 2015 07:13:40 -0700 Message-ID: <55CF4910.20109@berkeley.edu> Date: Sat, 15 Aug 2015 10:13:36 -0400 From: Erik Wilde User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.10; rv:31.0) Gecko/20100101 Thunderbird/31.6.0 MIME-Version: 1.0 To: link-relations@ietf.org Subject: Re: Link relation types for non-GET links References: In-Reply-To: Content-Type: text/plain; charset=windows-1252; format=flowed Content-Transfer-Encoding: 7bit Archived-At: X-BeenThere: link-relations@ietf.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 15 Aug 2015 14:13:43 -0000 hello mike and klaus. On 2015-08-15 08:27, Klaus Hartke wrote: > Mike Kelly wrote: >> You can use a standard HAL link and a link relation if you ensure the link >> relation is a URL which can be dereferenced to retrieve a machine-readable >> description of the methods and messages that are possible for that link. >> Just think of it as machine readable link relation documentation. > That's an interesting idea. It basically adds a level of indirection, > which should be useful if many links have the same machine-readable > description of possible methods and payloads. However, I think I'd > prefer including that description directly at the link, so a client > does not have to dereference a URL to understand the link semantics. if you have a standalone format (such as https://github.com/dret/I-D/tree/master/link-desc or whatever you come up with to represent link interaction information), then embedding it or making it external or allowing both is a simple design choice and flip for anybody using it. our main driver for allowing this kind of flexibility was the scenario mentioned before: the general link relation type might define a number of parameters clients can submit, but the specific runtime info could be more constrained ("only 42 pages you can GET"), and clients could adjust accordingly. ideally, there would be some kind of "inheritance model" (effective link interaction semantics are a combination of the generic ones, and runtime info can selectively overwrite), but we never got far enough to really have a well-defined model for that. cheers, dret. -- erik wilde | mailto:dret@berkeley.edu - tel:+1-510-2061079 | | UC Berkeley - School of Information (ISchool) | | http://dret.net/netdret http://twitter.com/dret | From nobody Sat Aug 15 08:15:11 2015 Return-Path: X-Original-To: link-relations@ietfa.amsl.com Delivered-To: link-relations@ietfa.amsl.com Received: from localhost (ietfa.amsl.com [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 01C141B2F2F for ; Sat, 15 Aug 2015 08:15:10 -0700 (PDT) X-Virus-Scanned: amavisd-new at amsl.com X-Spam-Flag: NO X-Spam-Score: -0.928 X-Spam-Level: X-Spam-Status: No, score=-0.928 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, FM_FORGED_GMAIL=0.622, HELO_EQ_DE=0.35] autolearn=no Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id ity3ey4KuDPV for ; Sat, 15 Aug 2015 08:15:08 -0700 (PDT) Received: from mailhost.informatik.uni-bremen.de (mailhost.informatik.uni-bremen.de [IPv6:2001:638:708:30c9::12]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 3CDF21B2F2D for ; Sat, 15 Aug 2015 08:15:08 -0700 (PDT) X-Virus-Scanned: amavisd-new at informatik.uni-bremen.de Received: from submithost.informatik.uni-bremen.de (submithost.informatik.uni-bremen.de [134.102.201.11]) by mailhost.informatik.uni-bremen.de (8.14.5/8.14.5) with ESMTP id t7FFF5v2009647 for ; Sat, 15 Aug 2015 17:15:05 +0200 (CEST) Received: from mail-ig0-f172.google.com (mail-ig0-f172.google.com [209.85.213.172]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by submithost.informatik.uni-bremen.de (Postfix) with ESMTPSA id 3mtlYh70krz4vL3 for ; Sat, 15 Aug 2015 17:15:04 +0200 (CEST) Received: by igfj19 with SMTP id j19so29610100igf.1 for ; Sat, 15 Aug 2015 08:15:03 -0700 (PDT) X-Received: by 10.50.79.197 with SMTP id l5mr8322828igx.28.1439651703603; Sat, 15 Aug 2015 08:15:03 -0700 (PDT) MIME-Version: 1.0 Received: by 10.79.111.209 with HTTP; Sat, 15 Aug 2015 08:14:24 -0700 (PDT) In-Reply-To: <55CF2EBE.5060203@gmx.de> References: <55CC8C1D.9060900@gmx.de> <55CF2EBE.5060203@gmx.de> From: Klaus Hartke Date: Sat, 15 Aug 2015 17:14:24 +0200 Message-ID: Subject: Re: Link relation types for non-GET links To: Julian Reschke Content-Type: text/plain; charset=UTF-8 Archived-At: Cc: link-relations X-BeenThere: link-relations@ietf.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 15 Aug 2015 15:15:10 -0000 Julian Reschke wrote: > The link relation by definition can not be "unsafe". Ah, terminology. I meant to say that there are links with link relation types that indicate that the client should use a method other than GET when following the link ("non-GET link" for short). If these have the same syntactic form as "GET links" in a representation, and a spider does not know the link relation type, the spider does not know which method to use to follow the link. However, if they have distinct syntactic forms, a spider could at least follow the "GET links", even without understanding the link semantics in detail. This seems to be a useful feature. (BTW, there is a section titled "Unsafe Link Relations" in the RESTful Web APIs book [1].) > The link is always safe; it's the method applied to the link target which > might not. Maybe it's then a good idea to find better terms than "safe" and "unsafe" (or "GET" and "non-GET") to refer to different types of links. I hope we can agree that there are two types of links: - Links that cause a transition in the client-side application state when followed, and - Links that cause a transition in the server-side resource state when followed. I'm calling these "links" and "forms" in my draft [2], respectively, but I'm happy to switch to other terms if there is consensus on how they should be called. Klaus [1] http://restfulwebapis.com/ [2] https://tools.ietf.org/html/draft-hartke-core-apps-01#section-2.4 From nobody Sat Aug 15 08:47:39 2015 Return-Path: X-Original-To: link-relations@ietfa.amsl.com Delivered-To: link-relations@ietfa.amsl.com Received: from localhost (ietfa.amsl.com [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 6BFA71B2F7C for ; Sat, 15 Aug 2015 08:47:38 -0700 (PDT) X-Virus-Scanned: amavisd-new at amsl.com X-Spam-Flag: NO X-Spam-Score: -1.487 X-Spam-Level: X-Spam-Status: No, score=-1.487 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, FM_FORGED_GMAIL=0.622, FREEMAIL_FROM=0.001, HTML_MESSAGE=0.001, J_CHICKENPOX_38=0.6, RCVD_IN_DNSWL_LOW=-0.7, SPF_PASS=-0.001, T_RP_MATCHES_RCVD=-0.01] autolearn=no Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id HOc6WPBhw2vo for ; Sat, 15 Aug 2015 08:47:36 -0700 (PDT) Received: from nm17-vm2.bullet.mail.ne1.yahoo.com (nm17-vm2.bullet.mail.ne1.yahoo.com [98.138.91.93]) (using TLSv1 with cipher ECDHE-RSA-RC4-SHA (128/128 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 5AF441B2F7B for ; Sat, 15 Aug 2015 08:47:36 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yahoo.com; s=s2048; t=1439653655; bh=VLkWOLDO2RWx7x4sbntIPPp7wvEypRAfwSazKJQ/S0c=; h=In-Reply-To:References:From:Date:Subject:To:Cc:From:Subject; b=Al+Q+gx1VbnJ95nFniu6r5HOw+h8gehybZKvPP5nnO7zynyEeAukbFstI+AjhnuyCbdmFJgoLmdQT8Ev70wr+FIMsfawCxoi0TBm1Lpb/W/fVQT1lavH6Zc5QqndHOHM0asfBl6vzuxQZV7ZTwX3Uss4B/C+Y9VApP59om0s8MGIARbiz7LCTj+/ShCNlptQQmIwICViLUHO1QBuQ1vl+LFTPVa2eou0pb0Q0bs20Mfspk1qNw98gE6VKYMZFW8SyGvoMWZAWc8CPDa4vyogzNcL3GvxdEPtyggBjV+ON6leOVh0UIYJ0TRtHIoHB9pkElpIY+PwDtAuPd5fb58Y8A== Received: from [98.138.226.176] by nm17.bullet.mail.ne1.yahoo.com with NNFMP; 15 Aug 2015 15:47:35 -0000 Received: from [98.138.226.125] by tm11.bullet.mail.ne1.yahoo.com with NNFMP; 15 Aug 2015 15:47:35 -0000 Received: from [127.0.0.1] by smtp204.mail.ne1.yahoo.com with NNFMP; 15 Aug 2015 15:47:35 -0000 X-Yahoo-Newman-Id: 698589.29046.bm@smtp204.mail.ne1.yahoo.com X-Yahoo-Newman-Property: ymail-3 X-YMail-OSG: 13rRBbEVM1mp_d5hM0HZUaJqbOcbwNSRrDTwHsvbR5iLi7u 2sMTxqGPwE7mPoouB0yF4D9AQVNFI..twSwCRg8lKcwXk.CDYDDu6yVRDimA _u74jTllWRYQisThLD5JUEBBYCg6IEoH.iFz44AowjAIKdX_2FOqooThBq2Q msqwDWsrXTkjLmsGKGx1Y16gzRNlYmx2SGnms4f8VhJo9ALrajCAdymo8ip9 _eejnzjheByq47Fk0DToy13k7brDGd7ZRsodeO9ejbv6.7MmLvHxNs0XF1BK pjL2l8Be8SKIj6y4Nvywph_i08MwcqGm7TW_wjM_BXzZSDLIorPcyrKvSby_ IV.Zl1B6eseGiQXUq6BmqKDS1B5HtK_CNG_2bRezoZG4PZbbiRaDK474F6vm tXBHprv1aAhS2KfTA1XiiMOFzgvGrRnyf6y6qlr4jNjaY2JXbDl8TqMPXmKm jzGglIN.EQ0phBydk40shCrnm9VmQup1WNi0rxJa1mC7i5nAvQPoc3jxpn8Y 4.kCZcXb8M65R1.wwTB9Jwqr.cpL1tQ-- X-Yahoo-SMTP: i12ABOmswBAkPG1PnjmsmmFRWA-- Received: by igbjg10 with SMTP id jg10so29950759igb.0 for ; Sat, 15 Aug 2015 08:47:35 -0700 (PDT) X-Gm-Message-State: ALoCoQkiUQNkzmz9yhY34WwNHPSfR/bAP71Wt2sOa8pLleVfmSbxl7uenlLUB01QefCEw8p36N7i X-Received: by 10.50.143.2 with SMTP id sa2mr7044785igb.92.1439653655102; Sat, 15 Aug 2015 08:47:35 -0700 (PDT) MIME-Version: 1.0 Received: by 10.79.21.195 with HTTP; Sat, 15 Aug 2015 08:47:15 -0700 (PDT) In-Reply-To: References: <55CC8C1D.9060900@gmx.de> <55CF2EBE.5060203@gmx.de> From: mike amundsen Date: Sat, 15 Aug 2015 11:47:15 -0400 Message-ID: Subject: Re: Link relation types for non-GET links To: Klaus Hartke Content-Type: multipart/alternative; boundary=001a1134b594b66ff0051d5b7c48 Archived-At: Cc: Julian Reschke , link-relations X-BeenThere: link-relations@ietf.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 15 Aug 2015 15:47:38 -0000 --001a1134b594b66ff0051d5b7c48 Content-Type: text/plain; charset=UTF-8 Klaus: I think an important design decision is whether you want to overload a link rel value ("edit", "item", "collection", "payment") with protocol-level information like "idempotent", "safe", etc. or rendering information like "transclude", "immutable:, etc. My advice is to keep them separate. Your definitions in 2.4 are a bit unclear (by my reading) _link_ promises "navigation" ("transclude=false") but does it also promise "safe=true"? _embedded_link_ promisses "transclude=true" but does it also promise "safe=true"? _templated_link_ promises "mutability" but what of safety and transclusion? _form_ is promising "safe=false" but some are idempotent, some not. esp. when working with automated systems, you'll need to sort this out explicitly -- preferably inband, i suspect. i wrote up a draft paper in 2011 that talks about these[1] "hypermedia aspects" (safety, idempotence, mutability, and transclusion) and have a web page that lists the most common hypermedia factors[2] (that page could use some "love", tho ). This might help you in designing a media type that does a good job supporting a wide range of protocol-agnostic actions and promises. Finally, I am working on a media type design specifically aimed at automated agents -- Uniform Basis for Exchanging Representations (UBER -- I know...)[3] that you are free to use that for inspiration, caution, etc. cheers [1] http://www.w3.org/2011/10/integration-workshop/p/hypermedia-oriented-design.pdf [2] http://amundsen.com/hypermedia/hfactor/ [3] http://uberhypermedia.com mamund +1.859.757.1449 skype: mca.amundsen http://amundsen.com/blog/ http://twitter.com/mamund https://github.com/mamund http://linkedin.com/in/mamund On Sat, Aug 15, 2015 at 11:14 AM, Klaus Hartke wrote: > Julian Reschke wrote: > > The link relation by definition can not be "unsafe". > > Ah, terminology. I meant to say that there are links with link > relation types that indicate that the client should use a method other > than GET when following the link ("non-GET link" for short). If these > have the same syntactic form as "GET links" in a representation, and a > spider does not know the link relation type, the spider does not know > which method to use to follow the link. However, if they have distinct > syntactic forms, a spider could at least follow the "GET links", even > without understanding the link semantics in detail. This seems to be a > useful feature. > > (BTW, there is a section titled "Unsafe Link Relations" in the RESTful > Web APIs book [1].) > > > The link is always safe; it's the method applied to the link target which > > might not. > > Maybe it's then a good idea to find better terms than "safe" and > "unsafe" (or "GET" and "non-GET") to refer to different types of > links. I hope we can agree that there are two types of links: > > - Links that cause a transition in the client-side application state > when followed, and > - Links that cause a transition in the server-side resource state when > followed. > > I'm calling these "links" and "forms" in my draft [2], respectively, > but I'm happy to switch to other terms if there is consensus on how > they should be called. > > Klaus > > [1] http://restfulwebapis.com/ > [2] https://tools.ietf.org/html/draft-hartke-core-apps-01#section-2.4 > > _______________________________________________ > link-relations mailing list > link-relations@ietf.org > https://www.ietf.org/mailman/listinfo/link-relations > --001a1134b594b66ff0051d5b7c48 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable
Klaus:

I think an important design deci= sion is whether you want to overload a link rel value ("edit", &q= uot;item", "collection", "payment") with protocol-= level information like "idempotent", "safe", etc. or re= ndering information like "transclude", "immutable:, etc.

My advice is to keep them separate.

Your definitions in 2.4 are a bit unclear (by my reading)
_link_ promises "navigation" ("transclude=3Dfalse") bu= t does it also promise "safe=3Dtrue"?
_embedded_link_ p= romisses "transclude=3Dtrue" but does it also promise "safe= =3Dtrue"?
_templated_link_ promises "mutability&quo= t; but what of safety and transclusion?
_form_ is promising "= ;safe=3Dfalse" but some are idempotent, some not.

=
esp. when working with automated systems, you'll need to sort this= out explicitly -- preferably inband, i suspect.

i= wrote up a draft paper in 2011 that talks about these[1] "hypermedia = aspects" (safety, idempotence, mutability, and transclusion) and have = a web page that lists the most common hypermedia factors[2] (that page coul= d use some "love", tho <g>).=C2=A0 This might help you in d= esigning a media type that does a good job supporting a wide range of proto= col-agnostic actions and promises.

Finally, I am w= orking on a media type design specifically aimed at automated agents -- Uni= form Basis for Exchanging Representations (UBER -- I know...)[3] that you a= re free to use that for inspiration, caution, etc.

cheers



=





On Sat, Aug 15, 2015 at 11:14 AM, Klaus Hart= ke <hartke@tzi.org> wrote:
Julian Reschke wrote:
> The link relation by definition can not be "unsafe".

Ah, terminology. I meant to say that there are links with link
relation types that indicate that the client should use a method other
than GET when following the link ("non-GET link" for short). If t= hese
have the same syntactic form as "GET links" in a representation, = and a
spider does not know the link relation type, the spider does not know
which method to use to follow the link. However, if they have distinct
syntactic forms, a spider could at least follow the "GET links", = even
without understanding the link semantics in detail. This seems to be a
useful feature.

(BTW, there is a section titled "Unsafe Link Relations" in the RE= STful
Web APIs book [1].)

> The link is always safe; it's the method applied to the link targe= t which
> might not.

Maybe it's then a good idea to find better terms than "safe= " and
"unsafe" (or "GET" and "non-GET") to refer to= different types of
links. I hope we can agree that there are two types of links:

- Links that cause a transition in the client-side application state
when followed, and
- Links that cause a transition in the server-side resource state when foll= owed.

I'm calling these "links" and "forms" in my draft [= 2], respectively,
but I'm happy to switch to other terms if there is consensus on how
they should be called.

Klaus

[1] http://restfulwebapis.com/
[2] https://tools.ietf.org/html/dra= ft-hartke-core-apps-01#section-2.4

_______________________________________________
link-relations mailing list
link-relations@ietf.org
https://www.ietf.org/mailman/listinfo/link-relat= ions

--001a1134b594b66ff0051d5b7c48-- From nobody Sat Aug 15 10:57:11 2015 Return-Path: X-Original-To: link-relations@ietfa.amsl.com Delivered-To: link-relations@ietfa.amsl.com Received: from localhost (ietfa.amsl.com [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 8348B1A21A8 for ; Sat, 15 Aug 2015 10:57:10 -0700 (PDT) X-Virus-Scanned: amavisd-new at amsl.com X-Spam-Flag: NO X-Spam-Score: 0.472 X-Spam-Level: X-Spam-Status: No, score=0.472 tagged_above=-999 required=5 tests=[BAYES_05=-0.5, FM_FORGED_GMAIL=0.622, HELO_EQ_DE=0.35] autolearn=no Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id DzeBoGi9ss6h for ; Sat, 15 Aug 2015 10:57:08 -0700 (PDT) Received: from mailhost.informatik.uni-bremen.de (mailhost.informatik.uni-bremen.de [IPv6:2001:638:708:30c9::12]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 3CC4A1A21A5 for ; Sat, 15 Aug 2015 10:57:08 -0700 (PDT) X-Virus-Scanned: amavisd-new at informatik.uni-bremen.de Received: from submithost.informatik.uni-bremen.de (submithost.informatik.uni-bremen.de [IPv6:2001:638:708:30c9::b]) by mailhost.informatik.uni-bremen.de (8.14.5/8.14.5) with ESMTP id t7FHv56U028179 for ; Sat, 15 Aug 2015 19:57:05 +0200 (CEST) Received: from mail-ig0-f171.google.com (mail-ig0-f171.google.com [209.85.213.171]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by submithost.informatik.uni-bremen.de (Postfix) with ESMTPSA id 3mtq8c5dyjz4tvK for ; Sat, 15 Aug 2015 19:57:04 +0200 (CEST) Received: by igfj19 with SMTP id j19so32243648igf.0 for ; Sat, 15 Aug 2015 10:57:03 -0700 (PDT) X-Received: by 10.50.87.74 with SMTP id v10mr9117074igz.37.1439661423261; Sat, 15 Aug 2015 10:57:03 -0700 (PDT) MIME-Version: 1.0 Received: by 10.79.111.209 with HTTP; Sat, 15 Aug 2015 10:56:23 -0700 (PDT) In-Reply-To: References: <55CC8C1D.9060900@gmx.de> <55CF2EBE.5060203@gmx.de> From: Klaus Hartke Date: Sat, 15 Aug 2015 19:56:23 +0200 Message-ID: Subject: Re: Link relation types for non-GET links To: mike amundsen Content-Type: text/plain; charset=UTF-8 Archived-At: Cc: link-relations X-BeenThere: link-relations@ietf.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 15 Aug 2015 17:57:10 -0000 Mike Amundsen wrote: > I think an important design decision is whether you want to overload a link > rel value ("edit", "item", "collection", "payment") with protocol-level > information like "idempotent", "safe", etc. or rendering information like > "transclude", "immutable:, etc. > > My advice is to keep them separate. That's exactly what my initial question was about: should all hypermedia controls take the shape of a link, with the link relation types providing all the necessary details (like request method, presentation, etc.), or should a media type provide a number of syntactically different hypermedia controls so that the relation type really only indicates the semantic meaning of the control. The existence of the "edit" link relation type seems to point at the former, although I would agree that it's probably better to keep it separated and do the latter. So, because I like HAL, I would extend HAL with forms, resulting in a representation that might look like this: { "_links": { "terms-of-service": { "href": "http://example.org/tos", "type": "text/html" }, }, "_forms": { "create-a-new-item-in": { "href": "http://example.org/collection/", "method": "POST", "accept": "application/x-www-form-urlencoded", "fields": [ "firstName", "lastName", "eMail" ] } }, ... } The "create-a-new-item-in" non-GET link is kept separate from the "terms-of-service" GET link, and has * a context (a collection resource), * a "form relation type" that enables a client to decide whether to follow this link or not, * a request method which indicates that following the link changes resource state, is not safe and not idempotent, and * a description of the payload that the server expects in the request when following the link. > Your definitions in 2.4 are a bit unclear (by my reading) > _link_ promises "navigation" ("transclude=false") but does it also promise > "safe=true"? > _embedded_link_ promisses "transclude=true" but does it also promise > "safe=true"? > _templated_link_ promises "mutability" but what of safety and transclusion? > _form_ is promising "safe=false" but some are idempotent, some not. > > esp. when working with automated systems, you'll need to sort this out > explicitly -- preferably inband, i suspect. I actually based that on H-Factor Link Support, except that I combined LN and LI: * link = LO (replaces the application state, safe [1], idempotent [2]) * embedding link = LE (adds to the application state, safe, idempotent) * templated link = LT (replaces the application state, safe, idempotent) * form = LN / LI (changes resource state, not safe, may or may not be idempotent; includes the method to use, so the client would know if it's idempotent or not) (I'm not sure I understand what you mean by "mutability".) > i wrote up a draft paper in 2011 that talks about these[1] "hypermedia > aspects" (safety, idempotence, mutability, and transclusion) and have a web > page that lists the most common hypermedia factors[2] (that page could use > some "love", tho ). This might help you in designing a media type that > does a good job supporting a wide range of protocol-agnostic actions and > promises. The H-Factor page is actually printed and sitting on my desk :-) > Finally, I am working on a media type design specifically aimed at automated > agents -- Uniform Basis for Exchanging Representations (UBER -- I > know...)[3] that you are free to use that for inspiration, caution, etc. Thanks, this looks interesting. Klaus [1] http://tools.ietf.org/html/rfc7231#section-4.2.1 [2] http://tools.ietf.org/html/rfc7231#section-4.2.2 From nobody Sat Aug 15 11:05:23 2015 Return-Path: X-Original-To: link-relations@ietfa.amsl.com Delivered-To: link-relations@ietfa.amsl.com Received: from localhost (ietfa.amsl.com [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 02C6E1A6F2F for ; Sat, 15 Aug 2015 11:05:22 -0700 (PDT) X-Virus-Scanned: amavisd-new at amsl.com X-Spam-Flag: NO X-Spam-Score: -4.211 X-Spam-Level: X-Spam-Status: No, score=-4.211 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, RCVD_IN_DNSWL_MED=-2.3, SPF_PASS=-0.001, T_RP_MATCHES_RCVD=-0.01] autolearn=ham Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id Iwr99bzis_tZ for ; Sat, 15 Aug 2015 11:05:20 -0700 (PDT) Received: from cm01fe.IST.Berkeley.EDU (cm01fe.IST.Berkeley.EDU [169.229.218.142]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 9436E1A6F29 for ; Sat, 15 Aug 2015 11:05:20 -0700 (PDT) Received: from 205-237-53-208.static.cgocable.ca ([205.237.53.208] helo=dretair11.local) by cm01fe.ist.berkeley.edu with esmtpsa (TLSv1:AES128-SHA:128) (Exim 4.76) (auth plain:dret@berkeley.edu) (envelope-from ) id 1ZQfpT-0005Z9-5U; Sat, 15 Aug 2015 11:05:17 -0700 Message-ID: <55CF7F58.3080806@berkeley.edu> Date: Sat, 15 Aug 2015 14:05:12 -0400 From: Erik Wilde User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.10; rv:31.0) Gecko/20100101 Thunderbird/31.6.0 MIME-Version: 1.0 To: link-relations Subject: Re: Link relation types for non-GET links References: <55CC8C1D.9060900@gmx.de> <55CF2EBE.5060203@gmx.de> In-Reply-To: Content-Type: text/plain; charset=windows-1252; format=flowed Content-Transfer-Encoding: 7bit Archived-At: X-BeenThere: link-relations@ietf.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 15 Aug 2015 18:05:22 -0000 hello klaus. On 2015-08-15 13:56, Klaus Hartke wrote: > Mike Amundsen wrote: >> I think an important design decision is whether you want to overload a link >> rel value ("edit", "item", "collection", "payment") with protocol-level >> information like "idempotent", "safe", etc. or rendering information like >> "transclude", "immutable:, etc. My advice is to keep them separate. > That's exactly what my initial question was about: should all > hypermedia controls take the shape of a link, with the link relation > types providing all the necessary details (like request method, > presentation, etc.), or should a media type provide a number of > syntactically different hypermedia controls so that the relation type > really only indicates the semantic meaning of the control. you can go both ways, and different people have different opinions. my meta-opinion is that there is no "right way" of doing it, and my meta-guidance is to at least always be consistent in the set of services or media types you're designing. my non-meta-opinion is like mike's: keep the link relations general and generic, just specific enough so that hypermedia controls can be identified in representations. then design the representation to provide all the details that your scenario might need. here's my reasoning: - this way you keep the existing/registered link relations to a minimum, by not assuming that every little piece of information is implied in the link relation type. instead, that's the job of the link's context and can be adjusted as needed. - this way you also can make certain mechanisms (such as the link descriptions i am working on) reusable, so that they can be used for *any* kind of link relation type where you might want to use them. to me, this is a question of separation of concerns, but i have had long discussions with that with people leaning the opposite direction. like i said, the most important thing: pick a style and be consistent. cheers, dret. -- erik wilde | mailto:dret@berkeley.edu - tel:+1-510-2061079 | | UC Berkeley - School of Information (ISchool) | | http://dret.net/netdret http://twitter.com/dret |