Webinar: RESTful API Design, Second Edition - API Craft

The old Google Groups will be going away soon, but your browser is incompatible with the new version.
Message from discussion Webinar: RESTful API Design, Second Edition
Received-SPF: pass (google.com: domain of web...@gmail.com designates 209.85.214.53 as permitted sender) client-ip=209.85.214.53;
MIME-Version: 1.0
In-Reply-To: <CAEuS_0X_ROP8_XKjRx2R5vpNxVuOdSZxWMiDuCU1ZuthcZ4T+Q@mail.gmail.com>
References: <074f9671-49c8-4299-84c8-052206fccc6d@a17g2000yqj.googlegroups.com>
 <28406846.483.1327777397000.JavaMail.geo-discussion-forums@vbek1> <CAEuS_0X_ROP8_XKjRx2R5vpNxVuOdSZxWMiDuCU1ZuthcZ4...@mail.gmail.com>
From: Ron <web...@gmail.com>
Date: Sun, 29 Jan 2012 07:50:34 +0200
Message-ID: <CADUozXEd-7+91mZ3asS9zML-jk6NXqXbxvvqDmSZObMZjtp...@mail.gmail.com>
Subject: Re: Webinar: RESTful API Design, Second Edition
To: api-craft@googlegroups.com
Content-Type: multipart/alternative; boundary=000e0ce02a9629aeaf04b7a4503e

--000e0ce02a9629aeaf04b7a4503e
Content-Type: text/plain; charset=UTF-8

Okay, that's definitely an interesting suggestion - a way to use the basic
CRUD operations to support additional types of data manipulation (as you
mentioned, it is, in fact, a change in the state of the entity).

What worries me still about this solution is that changing the state of an
entity does not permit a change in the entity itself, so while a regular
method=put will allow a body, a method=put&state=published will not. I'm
not talking about the technical aspects on how to manage it (even though
it's not that simple for itself), but rather referring as to how to
document it in a coherent way (and hopefully an automatic way as well).

As for the second point you've raised - had we talked a couple of months
ago, I would have completely disagreed.
Without going into two many details, let's say that our entities are
version-managed, and they have two types of ids - one that identifies the
entity "uniquely" and one per version of the entity.

The exposed API of:
/entities/{id}

refers to a specific state, regardless of the sandbox it currently (may)
reside in, where the {id} is the "unique" id that identifies the entity
regardless of its version.

Recently, we've made a few changes to the API that would allow us to
support your suggestion (and pass the sandbox id, for example, as a
parameter). However, there are a few security / design concerns I haven't
delved into here which make it more difficult to work towards your
suggestion. Also, since I skipped a few steps in the description of the
API, I see why it'd make sense to you that it would be a cleaner API - even
though we do have an out-side-the-sandbox-before-moving-to-a-different-db
state as well :)

I must say that I really appreciate your insight, especially as it gets me
thinking. I'm always looking for ways to challenge the API design.

On Sun, Jan 29, 2012 at 02:52, Brian Mulloy <br...@apigee.com> wrote:

> my thoughts:
>
> i would model this as a change of state and use a PUT (method=PUT) on
> the resource.
>
> /entities/5678?method=PUT
> state=published
>
> i think that's your option #2.
>
> on a different topic, you shouldn't need to specify more than 1 id in an
> URl.
>
> for example
>
> /sandboxes/1234/entities
>
> is ok, but
>
> /sandboxes/1234/entities/5678
>
> is probably redundant. just indicating
>
> /entities/5678
>
> should get you to the desired element.
>
> this might also make it cleaner to change the association from sandbox
> to the totally different db.
>
> On Sat, Jan 28, 2012 at 2:03 PM, Ron R <web...@gmail.com> wrote:
> > A little bit late to the party, but I'll join nonetheless.
> >
> > When I've first started the design of our API, I've watched the original
> > presentation on the topic, and found it quite insightful.
> > One of the approaches I followed was the use of method=put/delete in
> order
> > to avoid potential problems with clients passing on PUT and DELETE http
> > requests (for various reasons).
> >
> > On the same resource level, I sometimes needed additional operation
> types,
> > so I ended up using the "method" parameter to allow further logic.
> > I now fear this was a poor choice of design, and would like to consult
> > regarding it.
> >
> > I have a URL as such:
> > /sandboxes/{sandboxId}/entities/{entityId}
> >
> > It works great for GET, PUT, DELETE operations (again, per your logical
> > recommendation, POST is not allowed at that level).
> > Now, I need to allow a "publish" operation, which essentially takes the
> > entity out of the sandbox and pushes it into a completely different
> database
> > (that is, there's quite a lot of logic running behind the scenes).
> >
> > In my mind, I figured that a URL such as
> > /sandboxes/{sandboxId}/entities/{entityId}/publish would be bad, as it
> > incorporates a verb in it. However, using
> > /sandboxes/{sandboxId}/entities/{entityId}?method=publish is now also a
> bit
> > of a problem, when it comes to documentation.
> >
> > I end up having 3 possible calls for:
> > /sandboxes/{sandboxId}/entities/{entityId}
> >
> > method=delete - has no body
> > method=put - has a body with the update
> > method=publish - also, has no body
> >
> > I was going to use the project http://enunciate.codehaus.org to
> > automatically produce an API documentation, but alas, with the usage of
> the
> > method parameter, it just fails. I've sent an email to their mailing list
> > asking for suggestions. It was suggested to me to solve the delete and
> put
> > operations programmatically - I can generate a filter that will take the
> > method=put and method=delete and translate those to PUT and DELETE calls
> > before they hit my actual code. The problem now remains with the
> > method=publish operation (and mind you, in some cases we have more
> > operations we expose).
> >
> > Again, this fails when it comes to generating documentation to the API
> > automatically.
> >
> > Any suggestions on how to approach such an issue would be greatly
> > appreciated.
>

--000e0ce02a9629aeaf04b7a4503e
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr">Okay, that&#39;s definitely an interesting suggestion - a =
way to use the basic CRUD operations to support additional types of data ma=
nipulation (as you mentioned, it is, in fact, a change in the state of the =
entity).<br>

<br>What worries me still about this solution is that changing the state of=
 an entity does not permit a change in the entity itself, so while a regula=
r method=3Dput will allow a body, a method=3Dput&amp;state=3Dpublished will=
 not. I&#39;m not talking about the technical aspects on how to manage it (=
even though it&#39;s not that simple for itself), but rather referring as t=
o how to document it in a coherent way (and hopefully an automatic way as w=
ell).<br>

<br>As for the second point you&#39;ve raised - had we talked a couple of m=
onths ago, I would have completely disagreed.<br>Without going into two man=
y details, let&#39;s say that our entities are version-managed, and they ha=
ve two types of ids - one that identifies the entity &quot;uniquely&quot; a=
nd one per version of the entity.<br>

<br>The exposed API of:<br>/entities/{id}<br><br>refers to a specific state=
, regardless of the sandbox it currently (may) reside in, where the {id} is=
 the &quot;unique&quot; id that identifies the entity regardless of its ver=
sion.<br>

<br>Recently, we&#39;ve made a few changes to the API that would allow us t=
o support your suggestion (and pass the sandbox id, for example, as a param=
eter). However, there are a few security / design concerns I haven&#39;t de=
lved into here which make it more difficult to work towards your suggestion=
. Also, since I skipped a few steps in the description of the API, I see wh=
y it&#39;d make sense to you that it would be a cleaner API - even though w=
e do have an out-side-the-sandbox-before-moving-to-a-different-db state as =
well :)<br>

<br>I must say that I really appreciate your insight, especially as it gets=
 me thinking. I&#39;m always looking for ways to challenge the API design.<=
br><br><div class=3D"gmail_quote">On Sun, Jan 29, 2012 at 02:52, Brian Mull=
oy <span dir=3D"ltr">&lt;<a href=3D"mailto:br...@apigee.com">br...@apigee.c=
om</a>&gt;</span> wrote:<br>

<blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p=
x #ccc solid;padding-left:1ex">my thoughts:<br>
<br>
i would model this as a change of state and use a PUT (method=3DPUT) on<br>
the resource.<br>
<br>
/entities/<a href=3D"tel:5678" value=3D"+9725678">5678</a>?method=3DPUT<br>
state=3Dpublished<br>
<br>
i think that&#39;s your option #2.<br>
<br>
on a different topic, you shouldn&#39;t need to specify more than 1 id in a=
n URl.<br>
<br>
for example<br>
<br>
/sandboxes/1234/entities<br>
<br>
is ok, but<br>
<br>
/sandboxes/1234/entities/<a href=3D"tel:5678" value=3D"+9725678">5678</a><b=
r>
<br>
is probably redundant. just indicating<br>
<br>
/entities/<a href=3D"tel:5678" value=3D"+9725678">5678</a><br>
<br>
should get you to the desired element.<br>
<br>
this might also make it cleaner to change the association from sandbox<br>
to the totally different db.<br>
<div class=3D"HOEnZb"><div class=3D"h5"><br>
On Sat, Jan 28, <a href=3D"tel:2012" value=3D"+9722012">2012</a> at 2:03 PM=
, Ron R &lt;<a href=3D"mailto:web...@gmail.com">web...@gmail.com</a>&gt; wr=
ote:<br>
&gt; A little bit late to the party, but I&#39;ll join nonetheless.<br>
&gt;<br>
&gt; When I&#39;ve first started the design of our API, I&#39;ve watched th=
e original<br>
&gt; presentation on the topic, and found it quite insightful.<br>
&gt; One of the approaches I followed was the use of method=3Dput/delete in=
 order<br>
&gt; to avoid potential problems with clients passing on PUT and DELETE htt=
p<br>
&gt; requests (for various reasons).<br>
&gt;<br>
&gt; On the same resource level, I sometimes needed additional operation ty=
pes,<br>
&gt; so I ended up using the &quot;method&quot; parameter to allow further =
logic.<br>
&gt; I now fear this was a poor choice of design, and would like to consult=
<br>
&gt; regarding it.<br>
&gt;<br>
&gt; I have a URL as such:<br>
&gt; /sandboxes/{sandboxId}/entities/{entityId}<br>
&gt;<br>
&gt; It works great for GET, PUT, DELETE operations (again, per your logica=
l<br>
&gt; recommendation, POST is not allowed at that level).<br>
&gt; Now, I need to allow a &quot;publish&quot; operation, which essentiall=
y takes the<br>
&gt; entity out of the sandbox and pushes it into a completely different da=
tabase<br>
&gt; (that is, there&#39;s quite a lot of logic running behind the scenes).=
<br>
&gt;<br>
&gt; In my mind, I figured that a URL such as<br>
&gt; /sandboxes/{sandboxId}/entities/{entityId}/publish would be bad, as it=
<br>
&gt; incorporates a verb in it. However, using<br>
&gt; /sandboxes/{sandboxId}/entities/{entityId}?method=3Dpublish is now als=
o a bit<br>
&gt; of a problem, when it comes to documentation.<br>
&gt;<br>
&gt; I end up having 3 possible calls for:<br>
&gt; /sandboxes/{sandboxId}/entities/{entityId}<br>
&gt;<br>
&gt; method=3Ddelete - has no body<br>
&gt; method=3Dput - has a body with the update<br>
&gt; method=3Dpublish - also, has no body<br>
&gt;<br>
&gt; I was going to use the project <a href=3D"http://enunciate.codehaus.or=
g" target=3D"_blank">http://enunciate.codehaus.org</a> to<br>
&gt; automatically produce an API documentation, but alas, with the usage o=
f the<br>
&gt; method parameter, it just fails. I&#39;ve sent an email to their maili=
ng list<br>
&gt; asking for suggestions. It was suggested to me to solve the delete and=
 put<br>
&gt; operations programmatically - I can generate a filter that will take t=
he<br>
&gt; method=3Dput and method=3Ddelete and translate those to PUT and DELETE=
 calls<br>
&gt; before they hit my actual code. The problem now remains with the<br>
&gt; method=3Dpublish operation (and mind you, in some cases we have more<b=
r>
&gt; operations we expose).<br>
&gt;<br>
&gt; Again, this fails when it comes to generating documentation to the API=
<br>
&gt; automatically.<br>
&gt;<br>
&gt; Any suggestions on how to approach such an issue would be greatly<br>
&gt; appreciated.<br>
</div></div></blockquote></div><br></div>

--000e0ce02a9629aeaf04b7a4503e--
Create a group - Google Groups - Google Home - Terms of Service - Privacy Policy
Account Options
