Excellent article... We followed all of these Rest principals when we designed apis for HP cloud print (i think it will soon become public)..except
1) Representing all resources with noun - We had a tough time representing all resources with Noun. One of our APIs is
Post on \PrintJobs\ - creates a new print job
But printing can only start when all the data (content to be printed) is uploaded on the server. So client needed an API to tell the server that it can start printing..something like this..
\printjobs\1\print
\printjobs\1\cancel
one way we thought to avoid this was to have a represent it job state and client can change them like this..
\printjobs\1
Put : <job>
<state="print">
</job>
But there are cons
1. These were not actually states, these were actions(verbs)..because state would be initialized, printing etc..
so if client does Get after making it Put..it will get "printing" not "Print".
So we were tangling with keeping semantics clear and making it easy at the same time. Hence we went with these resources. Do you think it could modeled better?
2) When we think of versioning, we always assume that only the representation can be changed..why not behavior? Take for e.g. if api implementation changes but not representation..clients may be dependent upon the implementation (i know this is bad! since implementation details are getting leaked out from the API)
I agree! Making such api make it really confusing. And what if one have to support other verbs. Then, One will end creating apis for each verb. A programmer who is using this APIs knows about HTTP and he knows about verb..making it explicit in the url will make confusing for most developers.
1) Representing all resources with noun - We had a tough time representing all resources with Noun. One of our APIs is Post on \PrintJobs\ - creates a new print job
But printing can only start when all the data (content to be printed) is uploaded on the server. So client needed an API to tell the server that it can start printing..something like this..
\printjobs\1\print \printjobs\1\cancel
one way we thought to avoid this was to have a represent it job state and client can change them like this..
\printjobs\1 Put : <job> <state="print"> </job>
But there are cons
1. These were not actually states, these were actions(verbs)..because state would be initialized, printing etc.. so if client does Get after making it Put..it will get "printing" not "Print".
So we were tangling with keeping semantics clear and making it easy at the same time. Hence we went with these resources. Do you think it could modeled better?
2) When we think of versioning, we always assume that only the representation can be changed..why not behavior? Take for e.g. if api implementation changes but not representation..clients may be dependent upon the implementation (i know this is bad! since implementation details are getting leaked out from the API)
Thoughts?