Webinar: RESTful API Design, Second Edition

[Brian Mulloy]

This thread is for follow-up questions to the November 3rd webinar on
RESTful API design.

(webinar details here: http://t.co/32GUAin7)

[Nitin Krishna]

Would it be possible to get ppt beforehand?

[Birute Awasthi]

Hi Nitin, we will post the slides on http://www.slideshare.net/apigee
right after the webinar.

[Nitin Krishna]

thanks

[Birute Awasthi]

From: Ransom Murphy
Do you ever include the HTTP PATCH method (RFC 5789) in API
definitions?

On Nov 3, 10:19 am, Nitin Krishna <nk0...@gmail.com> wrote:

[Birute Awasthi]

From Robin Howlett: Twilio, SimpleGeo: Why duplicate HTTP status
codes within resources/representations?

[Birute Awasthi]

from Kevin Jensen: anyone has a good html/doc template for createing
REST documentation?

On Nov 3, 9:59 am, Brian Mulloy <br...@apigee.com> wrote:

[Birute Awasthi]

From William Cheung:
what do you recommend for navigating a graph or hierarchy? GET /graph/
root/subnode1/subnode2/ etc etc gets unwieldy even though it's natural

On Nov 3, 9:59 am, Brian Mulloy <br...@apigee.com> wrote:

[G. Hussain Chinoy]

Fantastic set of pragmatic and empirically derived best practices. I loved it and will definitely be applying those best practices, thank you!

Great question on generating REST service documentation, I second that. If there are any techniques, ideas, I'd love to hear them.

[Scott Regan]

just posted the video and slides for this API design webinar at
http://j.mp/uCKdkk . thanks again for your time and questions!

On Nov 3, 9:27 am, Nitin Krishna <nk0...@gmail.com> wrote:
> thanks
>
>
>
>
>
>
>
> On Thu, Nov 3, 2011 at 1:26 PM, Birute Awasthi <bir...@apigee.com> wrote:

> > Hi Nitin, we will post the slides onhttp://www.slideshare.net/apigee

[ndee]

thanks guys for showing us the right way in api design, great webinar
and slides *tumbsup*

On 9 Nov., 17:34, Scott Regan <sc...@apigee.com> wrote:
> just posted the video and slides for this API design webinar  athttp://j.mp/uCKdkk.  thanks again for your time and questions!

[Ron R]

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}

1. method=delete - has no body
2. method=put - has a body with the update
3. 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.

[Brian Mulloy]

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.

[Ron]

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.

[Fentie]

I know this thread is a getting a little long in the tooth but I just saw the presentation and I wanted some clarification on a point you made at the end. What did you mean by an API Virtualization layer? Some sort of generic API Request class with a set interface? It was emphasized as important but not really defined.

Thanks,
Brian

[Christophe Willemsen]

Hi,

I've just saw the webinar and I have to say it was awesome.

There was only one point where I can't be on your side : You use the url extension to determine the formate, I think it is bad practice for two reasons :

1. What about format versioning ?

2. You mix resource identification with content negociation, that are in fact 2 different concerns.

Regards,

Christophe

[Gary Diamond]

Fenti,

A followup series presentations called API Facade Pattern: Webinar shorts full series was created in March.  It doesn't go into code examples or specific technologies but it may be helpful.  There was talk about creating wiki pages about different technologies but I haven't found it yet.