API responsibilities - API Craft

The old Google Groups will be going away soon, but your browser is incompatible with the new version.
Message from discussion API responsibilities
Date: Tue, 13 Nov 2012 07:14:30 -0800 (PST)
From: Nicolas Faugout <nfaug...@lucca.fr>
To: api-craft@googlegroups.com
Message-Id: <0280eafa-56d3-49d3-a9aa-c3b574246ff4@googlegroups.com>
In-Reply-To: <0e11e686-154d-4470-86c8-f1203a7cf32d@googlegroups.com>
References: <b36318f2-6337-4b0c-a15b-7d8665b856ac@googlegroups.com>
 <0e11e686-154d-4470-86c8-f1203a7cf32d@googlegroups.com>
Subject: Re: API responsibilities
MIME-Version: 1.0
Content-Type: multipart/mixed; 
	boundary="----=_Part_1445_14364994.1352819670634"

------=_Part_1445_14364994.1352819670634
Content-Type: multipart/alternative; 
	boundary="----=_Part_1446_8332049.1352819670634"

------=_Part_1446_8332049.1352819670634
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

Hi Luke,

I think you are right advising me to have a welcome_email_sent boolean=20
attached to the user resource, that one is missing in my model !

This way, as you said, it is very easy to make the API send or not send the=
=20
email when creating a new user.

It seems common in REST APIs to make the API do an action by trying to=20
update the resource attribute corresponding to that action.

I will stick with that idea and throw the noNotification parameter away,=20
event if it has a scope wider than just the welcome email of creating a=20
user.

Thank you.


Le mardi 13 novembre 2012 16:07:11 UTC+1, Luke Stokes a =C3=A9crit :
>
> On Tuesday, November 13, 2012 7:47:05 AM UTC-6, Nicolas Faugout wrote:
>
>> When a user is created through a web interface, there is often a=20
>> notification email send to hi by the server handler.
>>
>> If that same user is created by sending a POST to an API, should it be=
=20
>> the API that sends the email or the service that called the API ?
>>
>> I would say :
>>
>> - by default, the API should send the email since it can be considered a=
s=20
>> a part of the entire process (inserting an entry into a database table,=
=20
>> creating a log entry in a log file, sending a notification email, ...)
>>
>>
> Yeah, I'd think about it this way also. I wonder if someone has a=20
> differing opinion...?
> =20
>
>> - but the API should also give the opportunity not to send email because=
=20
>> this part of the process is in fact not mandatory. For instance, when=20
>> creating several users with a bulk request and delaying the email when t=
he=20
>> service is really opened to them.
>>
>>
> Interesting. In this case, you'd have to keep track of who was emailed an=
d=20
> who wasn't so you could send the follow up email, right? Maybe you could=
=20
> argue for "welcome_email_sent" as a property of your user. If it is,=20
> POSTing with welcome_email_sent =3D 1 could send the email and 0 could av=
oid=20
> it. If someone loses there welcome email and wants another one, you could=
=20
> even build in a process to PATCH it back to 0 and then to 1 again (thus,=
=20
> triggering another welcome email).
> =20
>
>> POST /api/users =3D> create the user and sends the email
>>
>> POST /api/users?noNotification =3D> create the user
>>
>>
> This works also, but you'd either have to document it out of bounds so th=
e=20
> client knows to add that magic bean to the href it got back from the crea=
te=20
> user rel or you'd provide two different rels to point to your different=
=20
> uris:
>
> rel=3D"http://example.com/rels/create_user" href=3D"/api/users"
> rel=3D"http://example.com/rels/create_user_no_notification
> " href=3D"/api/users?noNotification"
> =20
>
>> Any suggestion would be grateful.
>>
>
> Those are my suggestions. Not sure if they're helpful. :)=20
>

------=_Part_1446_8332049.1352819670634
Content-Type: text/html; charset=utf-8
Content-Transfer-Encoding: quoted-printable

Hi Luke,<div><br></div><div>I think you are right advising me to have a&nbs=
p;welcome_email_sent boolean attached to the user resource, that one is mis=
sing in my model !</div><div><br></div><div>This way, as you said, it is ve=
ry easy to make the API send or not send the email when creating a new user=
.</div><div><br></div><div>It seems common in REST APIs to make the API do =
an action by trying to update the resource attribute corresponding to that =
action.</div><div><br></div><div>I will stick with that idea and throw the =
noNotification parameter away, event if it has a scope wider than just the =
welcome email of creating a user.</div><div><br></div><div>Thank you.</div>=
<div><br><br>Le mardi 13 novembre 2012 16:07:11 UTC+1, Luke Stokes a =C3=A9=
crit&nbsp;:<blockquote class=3D"gmail_quote" style=3D"margin: 0;margin-left=
: 0.8ex;border-left: 1px #ccc solid;padding-left: 1ex;">On Tuesday, Novembe=
r 13, 2012 7:47:05 AM UTC-6, Nicolas Faugout wrote:<br><blockquote class=3D=
"gmail_quote" style=3D"margin:0;margin-left:0.8ex;border-left:1px #ccc soli=
d;padding-left:1ex">When a user is created through a web interface, there i=
s often a notification email send to hi by the server handler.<div><br></di=
v><div>If that same user is created by sending a POST to an API, should it =
be the API that sends the email or the service that called the API ?</div><=
div><br></div><div>I would say :</div><div><br></div><div>- by default, the=
 API should send the email since it can be considered as a part of the enti=
re process (inserting an entry into a database table, creating a log entry =
in a log file, sending a notification email, ...)</div><div><br></div></blo=
ckquote><div><br></div><div>Yeah, I'd think about it this way also. I wonde=
r if someone has a differing opinion...?</div><div>&nbsp;</div><blockquote =
class=3D"gmail_quote" style=3D"margin:0;margin-left:0.8ex;border-left:1px #=
ccc solid;padding-left:1ex"><div></div><div>- but the API should also give =
the opportunity not to send email because this part of the process is in fa=
ct not mandatory. For instance, when creating several users with a bulk req=
uest and delaying the email when the service is really opened to them.</div=
><div><br></div></blockquote><div><br></div><div>Interesting. In this case,=
 you'd have to keep track of who was emailed and who wasn't so you could se=
nd the follow up email, right? Maybe you could argue for "welcome_email_sen=
t" as a property of your user. If it is, POSTing with welcome_email_sent =
=3D 1 could send the email and 0 could avoid it. If someone loses there wel=
come email and wants another one, you could even build in a process to PATC=
H it back to 0 and then to 1 again (thus, triggering another welcome email)=
.</div><div>&nbsp;</div><blockquote class=3D"gmail_quote" style=3D"margin:0=
;margin-left:0.8ex;border-left:1px #ccc solid;padding-left:1ex"><div></div>=
<div>POST /api/users =3D&gt; create the user and sends the email</div><div>=
<br></div><div>POST /api/users?noNotification =3D&gt; create the user</div>=
<div><br></div></blockquote><div><br></div><div>This works also, but you'd =
either have to document it out of bounds so the client knows to add that ma=
gic bean to the href it got back from the create user rel or you'd provide =
two different rels to point to your different uris:</div><div><br></div><di=
v>rel=3D"<a href=3D"http://example.com/rels/create_user" target=3D"_blank">=
http://example.com/rels/<wbr>create_user</a>" href=3D"/api/users"</div><div=
>rel=3D"<a href=3D"http://example.com/rels/create_user_no_notification" tar=
get=3D"_blank">http://example.com/rels/<wbr>create_user_no_notification</a>=
"&nbsp;<wbr>href=3D"/api/users?<wbr>noNotification"</div><div>&nbsp;</div><=
blockquote class=3D"gmail_quote" style=3D"margin:0;margin-left:0.8ex;border=
-left:1px #ccc solid;padding-left:1ex"><div></div><div>Any suggestion would=
 be grateful.</div></blockquote><div><br></div><div>Those are my suggestion=
s. Not sure if they're helpful. :)&nbsp;</div></blockquote></div>
------=_Part_1446_8332049.1352819670634--

------=_Part_1445_14364994.1352819670634--
Create a group - Google Groups - Google Home - Terms of Service - Privacy Policy
Account Options
