| Newsgroups |
gmane.comp.web.services.rest |
| Message-ID |
<CAK7gRgU4cU=4b5JMHgZA=7GjCqJirqvL0BeLwOqz-r2nJjimog@mail.gmail.com> |
--001a11477bfede2d960545f96d6b
Content-Type: text/plain; charset="UTF-8"
Hi all,
I would like to get some advice on how to improve the way we build our
hypermedia apis.
We currently use HAL as our base hypermedia format and all non safe
interactions are done using bare json documents submitted through http
posts. The link relations are simple identifiers which are not the proper
way to do it.
The problems that I can see are:
By using non standard link relations clients that are not produced by us
have no way to find the resources that the server provides.
By using bare json documents the clients have no way to know the format of
documents expected by the server making it harder for clients to be
developed and to keep them compatible to server when has to change.
I'm thinking about raising api "hateoas" level by stating that all non safe
interactions have to be done throughout HAL forms. That way clients can
inspect the forms and know if they are compatible with server. By doing
this I think that will ease both client development and maintenance. But I
still have the following doubts:
1 - should we use HAL forms instead of uri templates? We currently use uri
templates a lot but they don't have any built in mechanism to indicate
format and validation.
2 - when making the safe requests how can we give clients any way to check
the format of these responses? Should we use json schema?
To solve our link relation problem I was thinking about creating a
specification for inline relations using urns. I have to further develop
this idea but the basics are:
the urns would be composed of a set of properties. I was thinking about, at
least, three properties:
organization - A kind of hierarchical structure like a java package to
capture hierarchical nature of organizations
subject - The matter to which the operation is made to act
operation - action that will be carried on.
An example would be:
urn:Ilr:organization=com.myorganization,subject=order,operation=create
There would be 2 two kinds of inline relations: pointers and selectors.
Pointers indicate resources that are directly involved in fulfilling the
operation on the subject as stated in the urn. Selectors sets restrictions
on links in the resource.
For example:
The
pointer:urn:ilr:organization=com.myorganization,subject=order,action=create
points to the resource you have to use in order to create a client order
(in my case a hal form)
The selector:urn:ilr:organization:com.mycompany.* points to a resource that
contains all links to any sub organization of com.mycompany like
com.mycompany.mydepartment and all its subjects and operations.
This distinction will help on finding a resource in a decentralized
environment where resources can be add and removed without centralized
control.
As I said this have to be refined but I would like to know if there is
already something like this or even if this is a good idea.
Any help will be very appreciated!
Att,
Osvaldo Pina.
--001a11477bfede2d960545f96d6b
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/htm=
l4/strict.dtd">
<html>
<head>
</head>
=20
<body style=3D"background-color: #fff;">
<span style=3D"display:none"> </span>
<!--~-|**|PrettyHtmlStartT|**|-~-->
<div id=3D"ygrp-mlmsg" style=3D"position:relative;">
<div id=3D"ygrp-msg" style=3D"z-index: 1;">
<!--~-|**|PrettyHtmlEndT|**|-~-->
<div id=3D"ygrp-text" >
=20=20=20=20=20=20
=20=20=20=20=20=20
<p><div dir=3D"ltr"><div>Hi all,</div><div><br></div><div>I would lik=
e to get some advice on how to improve the way we build our hypermedia apis=
.</div><div>=C2=A0=C2=A0</div><div>We currently use HAL as our base hyperme=
dia format and all non safe interactions are done using bare json documents=
submitted through http posts. The link relations are simple identifiers wh=
ich are not the proper way to do it.</div><div><br></div><div>The problems =
that I can see are:</div><div>By using non standard link relations clients =
that are not produced by us have no way to find the resources that the serv=
er provides.</div><div>By using bare json documents the clients have no way=
to know the format of documents expected by the server making it harder fo=
r clients to be developed and to keep them compatible to server when has to=
change.</div><div><br></div><div>I'm thinking about raising api "=
hateoas" level by stating that all non safe interactions have to be do=
ne throughout HAL forms. That way clients can inspect the forms and know if=
they are compatible with server. By doing this I think that will ease both=
client development and maintenance. But I still have the following doubts:=
</div><div><br></div><div>1 - should we use HAL forms instead of uri templa=
tes? We currently use uri templates a lot but they don't have any built=
in mechanism to indicate format and validation.=C2=A0</div><div>2 - when m=
aking the safe requests how can we give clients any way to check the format=
of these responses? Should we use json schema?</div><div><br></div><div>To=
solve our link relation problem I was thinking about creating a specificat=
ion for inline relations using urns. I have to further develop this idea bu=
t the basics are:</div><div><br></div><div>the urns would be composed of a =
set of properties. I was thinking about, at least, three properties:</div><=
div>=C2=A0organization - A kind of hierarchical structure like a java packa=
ge to capture hierarchical nature of organizations</div><div>subject - The =
matter to which the operation is made to act</div><div>operation - action t=
hat will be carried on.</div><div><br></div><div>An example would be:=C2=A0=
</div><div>urn:Ilr:organization=3Dcom.myorganization,subject=3Dorder,operat=
ion=3Dcreate</div><div><br></div><div>There would be 2 two kinds of inline =
relations: pointers and selectors. Pointers indicate resources that are dir=
ectly involved in fulfilling the operation on the subject as stated in the =
urn. Selectors sets restrictions on links in the resource.=C2=A0</div><div>=
For example:</div><div><br></div><div>The pointer:urn:ilr:organization=3Dco=
m.myorganization,subject=3Dorder,action=3Dcreate points to the resource you=
have to use in order to create a client order (in my case a hal form)</div=
><div><br></div><div>The selector:urn:ilr:organization:com.mycompany.* poin=
ts to a resource that contains all links to any sub organization of com.myc=
ompany like com.mycompany.mydepartment and all its subjects and operations.=
</div><div><br></div><div>This distinction will help on finding a resource =
in a decentralized environment where resources can be add and removed witho=
ut centralized control.</div><div><br></div><div>As I said this have to be =
refined but I would like to know if there is already something like this or=
even if this is a good idea.</div><div><br></div><div>Any help will be ver=
y appreciated!</div><div><br></div><div>Att,</div><div>Osvaldo Pina.</div><=
/div>
</p>
</div>
=20=20=20=20=20
<!--~-|**|PrettyHtmlStart|**|-~-->
<div style=3D"color: #fff; height: 0;">__._,_.___</div>
=20=20=20=20=20=20=20=20=20=20
=20=20
=20
=20=20=20=20
<div style=3D"clear:both"> </div>
<div id=3D"fromDMARC" style=3D"margin-top: 10px;">
<hr style=3D"height:2px ; border-width:0; color:#E3E3E3; background=
-color:#E3E3E3;">
Posted by: Osvaldo Pina <[email protected]> <hr s=
tyle=3D"height:2px ; border-width:0; color:#E3E3E3; background-color:#E3E3E=
3;">
</div>
<div style=3D"clear:both"> </div>
<table cellspacing=3D4px style=3D"margin-top: 10px; margin-bottom: 10px=
; color: #2D50FD;">
<tbody>
<tr>
<td style=3D"font-size: 12px; font-family: arial; font-weight: bo=
ld; padding: 7px 5px 5px;" >
<a style=3D"text-decoration: none; color: #2D50FD=
" href=3D"https://groups.yahoo.com/neo/groups/rest-discuss/conversations/me=
ssages/19738;_ylc=3DX3oDMTJxaTE0bTluBF9TAzk3MzU5NzE0BGdycElkAzQzMTkyNTUEZ3J=
wc3BJZAMxNzA1NzAxMDE0BG1zZ0lkAzE5NzM4BHNlYwNmdHIEc2xrA3JwbHkEc3RpbWUDMTQ4ND=
MyMjA1Mw--?act=3Dreply&messageNum=3D19738">Reply via web post</a>
</td>
<td>•</td>
<td style=3D"font-size: 12px; font-family: arial; padding: 7px 5p=
x 5px;" >
<a href=3D"mailto:[email protected]?subject=3DRe%3A%20Ques=
tions%20about%20hypermedia%20api%20design" style=3D"text-decoration: none; =
color: #2D50FD;">
Reply to sender </a>
</td>
<td>•</td>
<td style=3D"font-size: 12px; font-family: arial; padding: 7px 5p=
x 5px;">
<a href=3D"mailto:[email protected]?subject=3DRe%3A%=
20Questions%20about%20hypermedia%20api%20design" style=3D"text-decoration: =
none; color: #2D50FD">
Reply to group </a>
</td>
<td>•</td>
<td style=3D"font-size: 12px; font-family: arial; padding: 7px 5p=
x 5px;" >
<a href=3D"https://groups.yahoo.com/neo/groups/rest-discuss/con=
versations/newtopic;_ylc=3DX3oDMTJlaHVhZmI1BF9TAzk3MzU5NzE0BGdycElkAzQzMTky=
NTUEZ3Jwc3BJZAMxNzA1NzAxMDE0BHNlYwNmdHIEc2xrA250cGMEc3RpbWUDMTQ4NDMyMjA1Mw-=
-" style=3D"text-decoration: none; color: #2D50FD">Start a New Topic</a>
</td>
<td>•</td>
<td style=3D"font-size: 12px; font-family: arial; padding: 7px 5p=
x 5px;color: #2D50FD;" >
<a href=3D"https://groups.yahoo.com/neo/groups/=
rest-discuss/conversations/topics/19738;_ylc=3DX3oDMTM2ZTJlZWhhBF9TAzk3MzU5=
NzE0BGdycElkAzQzMTkyNTUEZ3Jwc3BJZAMxNzA1NzAxMDE0BG1zZ0lkAzE5NzM4BHNlYwNmdHI=
Ec2xrA3Z0cGMEc3RpbWUDMTQ4NDMyMjA1MwR0cGNJZAMxOTczOA--" style=3D"text-decora=
tion: none; color: #2D50FD;">Messages in this topic</a>
(1)
</td>
</tr>
</tbody>
</table>
=20=20=20=20=20=20=20=20
<div id=3D"megaphoneModule">
<hr style=3D"height:2px ; border-width:0; color:#E3E3E3; backgr=
ound-color:#E3E3E3;">
<div>
<div class=3D"stream" style=3D"margin-bottom:10px;">
<div style=3D"background-color:white;">
<div class=3D"sn-img" style=3D"display:inline;"><img name=3D"tn=
_file" style=3D"padding:0px 10px;vertical-align:top;margin-top:5px;" src=3D=
"https://s.yimg.com/ru/static/images/yg/img/megaphone/1464031581_phpFA8bON"=
height=3D"82" width=3D"82"></div>
<div class=3D"mod-txt" style=3D"display:inline-block;">
<a rel=3D"nofollow" name=3D"sub_url" target=3D"_blank" href=
=3D"https://yho.com/1wwmgg" style=3D"color:#0000FF;display:block;margin-lef=
t:5px;text-decoration:none;"><span style=3D"font-size:15px;">Have you tried=
the highest rated email app?</span></a>
<div style=3D"max-width:530px;padding:2px 5px;">With 4.5 st=
ars in iTunes, the Yahoo Mail app is the highest rated email app on the mar=
ket. What are you waiting for? Now you can access all your inboxes (Gmail, =
Outlook, AOL and more) in one place. Never delete an email again with 1000G=
B of free cloud storage.</div>
</div>
</div>
</div> </div>=20=20
=20=20=20=20=20
<hr style=3D"height:2px ; border-width:0; color:#E3E3E3; background-col=
or:#E3E3E3;">
</div>
<!------- Start Nav Bar ------>
=20
<!-- |**|begin egp html banner|**| -->
<div id=3D"ygrp-vital" style=3D"background-color: #f2f2f2; font-family: Ver=
dana; font-size: 10px; margin-bottom: 10px; padding: 10px;">
<span id=3D"vithd" style=3D"font-weight: bold; color: #333; text-transf=
orm: uppercase; "><a href=3D"https://groups.yahoo.com/neo/groups/rest-discu=
ss/info;_ylc=3DX3oDMTJlZmJ0NTlqBF9TAzk3MzU5NzE0BGdycElkAzQzMTkyNTUEZ3Jwc3BJ=
ZAMxNzA1NzAxMDE0BHNlYwN2dGwEc2xrA3ZnaHAEc3RpbWUDMTQ4NDMyMjA1Mw--" style=3D"=
text-decoration: none;">Visit Your Group</a></span>
<ul style=3D"list-style-type: none; margin: 0; padding: 0; display: in=
line;">
</ul>
</div>
<div id=3D"ft" style=3D"font-family: Arial; font-size: 11px; margin-top: 5p=
x; padding: 0 2px 0 0; clear: both;">
<a href=3D"https://groups.yahoo.com/neo;_ylc=3DX3oDMTJkZXFqM3JsBF9TAzk3ND=
c2NTkwBGdycElkAzQzMTkyNTUEZ3Jwc3BJZAMxNzA1NzAxMDE0BHNlYwNmdHIEc2xrA2dmcARzd=
GltZQMxNDg0MzIyMDUz" style=3D"float: left;"><img src=3D"http://l.yimg.com/r=
u/static/images/yg/img/email/new_logo/logo-groups-137x15.png" height=3D"15"=
width=3D"137" alt=3D"Yahoo! Groups" style=3D"border: 0;"/></a>
<div style=3D"color: #747575; float: right;"> • <a href=3D"https://i=
nfo.yahoo.com/privacy/us/yahoo/groups/details.html" style=3D"text-decoratio=
n: none;">Privacy</a> • <a href=3D"mailto:rest-discuss-unsubscribe@yah=
oogroups.com?subject=3DUnsubscribe" style=3D"text-decoration: none;">Unsubs=
cribe</a> • <a href=3D"https://info.yahoo.com/legal/us/yahoo/utos/term=
s/" style=3D"text-decoration: none;">Terms of Use</a> </div>
</div>
<br>
<!-- |**|end egp html banner|**| -->
</div> <!-- ygrp-msg -->
=20
<!-- Sponsor -->
<!-- |**|begin egp html banner|**| -->
<div id=3D"ygrp-sponsor" style=3D"width:160px; float:right; clear:none; m=
argin:0 0 25px 0; background: #fff;">
<!-- Start Recommendations -->
<div id=3D"ygrp-reco">
</div>
<!-- End Recommendations -->
</div> <!-- |**|end egp html banner|**| -->
<div style=3D"clear:both; color: #FFF; font-size:1px;">.</div>
</div>
<img src=3D"http://geo.yahoo.com/serv?s=3D97359714/grpId=3D4319255/grpspI=
d=3D1705701014/msgId=3D19738/stime=3D1484322053" width=3D"1" height=3D"1"> =
<br>
<img src=3D"http://y.analytics.yahoo.com/fpc.pl?ywarid=3D515FB27823A7407E&a=
=3D10001310322279&js=3Dno&resp=3Dimg&cf12=3DCP" width=3D"1" height=3D"1">=20
<div style=3D"color: #fff; height: 0;">__,_._,___</div>
<!--~-|**|PrettyHtmlEnd|**|-~-->
</body>
<!--~-|**|PrettyHtmlStart|**|-~-->
<head>
<style type=3D"text/css">
<!--
#ygrp-mkp {
border: 1px solid #d8d8d8;
font-family: Arial;
margin: 10px 0;
padding: 0 10px;
}
#ygrp-mkp hr {
border: 1px solid #d8d8d8;
}
#ygrp-mkp #hd {
color: #628c2a;
font-size: 85%;
font-weight: 700;
line-height: 122%;
margin: 10px 0;
}
#ygrp-mkp #ads {
margin-bottom: 10px;
}
#ygrp-mkp .ad {
padding: 0 0;
}
#ygrp-mkp .ad p {
margin: 0;
}
#ygrp-mkp .ad a {
color: #0000ff;
text-decoration: none;
}
#ygrp-sponsor #ygrp-lc {
font-family: Arial;
}
#ygrp-sponsor #ygrp-lc #hd {
margin: 10px 0px;
font-weight: 700;
font-size: 78%;
line-height: 122%;
}
#ygrp-sponsor #ygrp-lc .ad {
margin-bottom: 10px;
padding: 0 0;
}
#actions {
font-family: Verdana;
font-size: 11px;
padding: 10px 0;
}
#activity {
background-color: #e0ecee;
float: left;
font-family: Verdana;
font-size: 10px;
padding: 10px;
}
#activity span {
font-weight: 700;
}
#activity span:first-child {
text-transform: uppercase;
}
#activity span a {
color: #5085b6;
text-decoration: none;
}
#activity span span {
color: #ff7900;
}
#activity span .underline {
text-decoration: underline;
}
.attach {
clear: both;
display: table;
font-family: Arial;
font-size: 12px;
padding: 10px 0;
width: 400px;
}
.attach div a {
text-decoration: none;
}
.attach img {
border: none;
padding-right: 5px;
}
.attach label {
display: block;
margin-bottom: 5px;
}
.attach label a {
text-decoration: none;
}
=20=20
blockquote {
margin: 0 0 0 4px;
}
.bold {
font-family: Arial;
font-size: 13px;
font-weight: 700;
}
.bold a {
text-decoration: none;
}
dd.last p a {
font-family: Verdana;
font-weight: 700;
}
dd.last p span {
margin-right: 10px;
font-family: Verdana;
font-weight: 700;
}
dd.last p span.yshortcuts {
margin-right: 0;
}
div.attach-table div div a {
text-decoration: none;
}
div.attach-table {
width: 400px;
}
div.file-title a, div.file-title a:active, div.file-title a:hover, div.fi=
le-title a:visited {
text-decoration: none;
}
div.photo-title a, div.photo-title a:active, div.photo-title a:hover, div=
.photo-title a:visited {
text-decoration: none;
}
div#ygrp-mlmsg #ygrp-msg p a span.yshortcuts {
font-family: Verdana;
font-size: 10px;
font-weight: normal;
}
.green {
color: #628c2a;
}
.MsoNormal {
margin: 0 0 0 0;
}
o {
font-size: 0;
}
#photos div {
float: left;
width: 72px;
}
#photos div div {
border: 1px solid #666666;
height: 62px;
overflow: hidden;
width: 62px;
}
#photos div label {
color: #666666;
font-size: 10px;
overflow: hidden;
text-align: center;
white-space: nowrap;
width: 64px;
}
#reco-category {
font-size: 77%;
}
#reco-desc {
font-size: 77%;
}
.replbq {
margin: 4px;
}
#ygrp-actbar div a:first-child {
/* border-right: 0px solid #000;*/
margin-right: 2px;
padding-right: 5px;
}
#ygrp-mlmsg {
font-size: 13px;
font-family: Arial, helvetica,clean, sans-serif;
*font-size: small;
*font: x-small;
}
#ygrp-mlmsg table {
font-size: inherit;
font: 100%;
}
#ygrp-mlmsg select, input, textarea {
font: 99% Arial, Helvetica, clean, sans-serif;
}
#ygrp-mlmsg pre, code {
font:115% monospace;
*font-size:100%;
}
#ygrp-mlmsg * {
line-height: 1.22em;
}
#ygrp-mlmsg #logo {
padding-bottom: 10px;
}
#ygrp-msg p a {
font-family: Verdana;
}
#ygrp-msg p#attach-count span {
color: #1E66AE;
font-weight: 700;
}
#ygrp-reco #reco-head {
color: #ff7900;
font-weight: 700;
}
#ygrp-reco {
margin-bottom: 20px;
padding: 0px;
}
#ygrp-sponsor #ov li a {
font-size: 130%;
text-decoration: none;
}
#ygrp-sponsor #ov li {
font-size: 77%;
list-style-type: square;
padding: 6px 0;
}=20
#ygrp-sponsor #ov ul {
margin: 0;
padding: 0 0 0 8px;
}
#ygrp-text {
font-family: Georgia;
}
#ygrp-text p {
margin: 0 0 1em 0;
}
#ygrp-text tt {
font-size: 120%;
}
#ygrp-vital ul li:last-child {
border-right: none !important;=20
}=20
-->
</style>
</head>
<!--~-|**|PrettyHtmlEnd|**|-~-->
</html>
<!-- end group email -->
--001a11477bfede2d960545f96d6b--