Re: [dcphp-dev] Building RESTful APIs

David, I wasn't there for your presentation - but this a strong email that I'll probably be saving for a long while.

-- 
Graham Christensen

On Sunday, August 5, 2012 at 1:30 PM, David wrote:

A couple of weeks ago, I did a presentation on "Building a Restful API for Big Data Search using Zend Framework".

I was reviewing my slides, and part 2 of the talk on building RESTful APIs was rushed--I did not spend enough time on this topic.  Let me clarify a couple of points.

First, I stated that "All resources have unique IDs."  And, I gave the following examples.

1.    http://www.sample.com/ID/

2.    http://www.sample.com/qualifier/ID/

3.    http://www.sample.com/ID/qualifer/

 

For example, in the following, "file" is a "qualifier" and "12345" is an "ID."  http://www.sample.com/file/12345/

So, the qualifier indicates the type of resource it is.  However, I failed to mention that the HTTP interface of GET, POST, PUT and DELETE are applied to unique IDs.  So, a standard form is:

·         POST http://www.sample.com/file -- creates a new resource.

·         GET http://www.sample.com/file/12345 -- gets 12345.

·         PUT http://www.sample.com/file/12345 -- updates or overwrites 12345.

·         DELETE http://www.sample.com/file/12345 -- deletes 12345.

 

I assumed that everyone knew that this was the standard form of REST.  LOL  I probably should not have made this assumption.

Then, I went on to state that:

·         A REST API must be hypertext driven, i.e., it must be driven by hyperlinks—the same way that you navigate the Web.

·         A REST API must be stateless—no sessions, no cookies.  The API should have no out of bound information at all.  The API should be completely self describing.

 

Someone asked question about how one tracks the state of an authorized/authenticated user versus one who is not authorized/authenticated.  I responded by saying that it is appropriate to pass an authorization token in every HTTP request when a user is authorized to use the API.  But, I probably should have stressed that the change of state from an unauthorized user to an authorized user should be hypertext driven.  In other words, in order for an API to be self-describing, you have to return information in a response to a request of how to become an authorized user and how to pass the authorization token.

This would have been a good segue into my recommendation to use Mike Amundsen's Collection+JSON - Hypermedia Type.  Mike's JSON hypermedia type provides facilities for templates, query templates and links.  By using links and templates, a user of the API would be able to figure out the next steps (e.g., how to pass an authorization token) without having to refer to some extra-API documentation.

Moreover, by using Mike's media type, the emphasis would be more on using hypertext to drive changes in state rather than an over reliance on constructing meaningful qualifiers. 

This is a big topic to try to cover in 15 minutes.  Sorry that I did not give more time and careful attention to discussing such a meaty topic. 

David

--
You received this message because you are subscribed to the Google
Group: "Washington, DC PHP Developers Group" - http://www.dcphp.net
To post, send email to washington-dcphp-group@googlegroups.com
To unsubscribe, send email to washington-dcphp-group+unsubscribe@googlegroups.com
For more options, visit this group at http://groups.google.com/group/washington-dcphp-group?hl=en

--
You received this message because you are subscribed to the Google
Group: "Washington, DC PHP Developers Group" - http://www.dcphp.net
To post, send email to washington-dcphp-group@googlegroups.com
To unsubscribe, send email to washington-dcphp-group+unsubscribe@googlegroups.com
For more options, visit this group at http://groups.google.com/group/washington-dcphp-group?hl=en