On Thu, Nov 3, 2011 at 1:26 PM, Birute Awasthi <bir...@apigee.com> wrote: > Hi Nitin, we will post the slides on http://www.slideshare.net/apigee > right after the webinar.
> On Nov 3, 10:19 am, Nitin Krishna <nk0...@gmail.com> wrote: > > Would it be possible to get ppt beforehand?
> > On Nov 3, 2011 12:59 PM, "Brian Mulloy" <br...@apigee.com> wrote:
> > > This thread is for follow-up questions to the November 3rd webinar on > > > RESTful API design.
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:
> 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 > > right after the webinar.
> > On Nov 3, 10:19 am, Nitin Krishna <nk0...@gmail.com> wrote:
> > > Would it be possible to get ppt beforehand?
> > > On Nov 3, 2011 12:59 PM, "Brian Mulloy" <br...@apigee.com> wrote:
> > > > This thread is for follow-up questions to the November 3rd webinar on
> > > > RESTful API design.
> just posted the video and slides for this API design webinar athttp://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 > > > right after the webinar.
> > > On Nov 3, 10:19 am, Nitin Krishna <nk0...@gmail.com> wrote:
> > > > Would it be possible to get ppt beforehand?
> > > > On Nov 3, 2011 12:59 PM, "Brian Mulloy" <br...@apigee.com> wrote:
> > > > > This thread is for follow-up questions to the November 3rd webinar on
> > > > > RESTful API design.
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.
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.
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.
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.
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.
A followup series presentations called API Facade Pattern: Webinar shorts full series<http://blog.apigee.com/detail/api_facade_pattern_webinar_shorts_full_...> 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.
On Wednesday, February 15, 2012 9:09:04 PM UTC-7, Fentie wrote:
> 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.
