Short Notes on RESTful APIs - Revision history

Admin at 21:14, 28 June 2014

2014-06-28T21:14:05Z

Admin at 20:43, 28 June 2014

2014-06-28T20:43:51Z

Admin: Created page with "'''WIP - check for updates later.''' Take this section with a pinch of salt. Also, see Disclaimer. == What is RESTful? == There is no standard for what REST..."

2014-06-28T20:23:53Z

Created page with "'''WIP - check for updates later.''' Take this section with a pinch of salt. Also, see Disclaimer. == What is RESTful? == There is no standard for what REST..."

New page

'''WIP - check for updates later.'''

Take this section with a pinch of salt. Also, see [[#Disclaimer|Disclaimer]].

== What is RESTful? ==

There is no standard for what RESTful API is, but there is a precedent on most of the functional specs. This list presents my preferences regarding the "gray" areas of the spec.

TODO - general definition

== Interface Layout ==

== Interface Recommendations ==

=== General ===

* '''''Use POST for both entity creation and update.'''''<br/>Typically, RESTful API's are expected to use POST for element creation, and PUT for element update. I'm not a big supporter of this, as analogous to majority of programming (scripting) languages where you use the same assignment operator for both variable creation and updating, you should use the same HTTP method.<br/>Also, you'll avoid discussions about what is entity creation and update, esp. in scenarios where you want to allow creation and updates of sub-entities, where either of those can be viewed as update of the entity itself.<br/>Also, note that often RESTful is not supposed to allow access to sub-entities, but it makes life so much easier, and costs you less traffic.

=== Specific ===

== Disclaimer ==

''This list is by no means supposed to represent any "standard view" of RESTful API's.''

''It does not represent opinions of any of the companies I work(ed) with.''

''It is my personal checklist when designing interfaces. Many points depend only on your taste.''

''Some of the opinions are even "not really RESTful" but make life easier for you as backend dev, or for your consumers.''

@@ Line 7: / Line 7: @@
 == What is RESTful? ==
-There is no standard for what REST API is, but there is a precedent on most of the functional specs. This list presents my preferences regarding the "gray" areas of the spec.
+There is no standard for what REST API is (it's an architectural style, not a protocol), but there is a precedent on most of the functional specs. This list presents my preferences regarding the "gray" areas of the spec.
 '''Representational state transfer (REST)''' is a way to create, read, update or delete information on a server using simple HTTP calls.
@@ Line 22: / Line 22: @@
 * Each message includes ''enough information'' to describe how to process the message.
-== Interface Layout ==
+Web-based REST APIs typically comply to:
 == Interface Recommendations ==
 * '''''Use POST for both entity creation and update.'''''<br/>Typically, REST API's are expected to use POST for element creation, and PUT for element update. I'm not a big supporter of this, as analogous to majority of programming (scripting) languages where you use the same assignment operator for both variable creation and updating, you should use the same HTTP method.<br/>Also, you'll avoid discussions about what is entity creation and update, esp. in scenarios where you want to allow creation and updates of sub-entities, where either of those can be viewed as update of the entity itself.<br/>Also, note that often REST is not supposed to allow access to sub-entities, but it makes life so much easier, and costs you less traffic.
-=== Specific ===
+* versioning - depends on expected lifetime of the API
 == Disclaimer ==

@@ Line 1: / Line 1: @@
 '''WIP - check for updates later.'''
 Take this section with a pinch of salt. Also, see [[#Disclaimer|Disclaimer]].
@@ Line 5: / Line 7: @@
 == What is RESTful? ==
-There is no standard for what RESTful API is, but there is a precedent on most of the functional specs. This list presents my preferences regarding the "gray" areas of the spec.
+There is no standard for what REST API is, but there is a precedent on most of the functional specs. This list presents my preferences regarding the "gray" areas of the spec.
-TODO - general definition
+REST has a ''uniform interface'':
 == Interface Layout ==
@@ Line 15: / Line 28: @@
 === General ===
-* '''''Use POST for both entity creation and update.'''''<br/>Typically, RESTful API's are expected to use POST for element creation, and PUT for element update. I'm not a big supporter of this, as analogous to majority of programming (scripting) languages where you use the same assignment operator for both variable creation and updating, you should use the same HTTP method.<br/>Also, you'll avoid discussions about what is entity creation and update, esp. in scenarios where you want to allow creation and updates of sub-entities, where either of those can be viewed as update of the entity itself.<br/>Also, note that often RESTful is not supposed to allow access to sub-entities, but it makes life so much easier, and costs you less traffic.
+* '''''Use POST for both entity creation and update.'''''<br/>Typically, REST API's are expected to use POST for element creation, and PUT for element update. I'm not a big supporter of this, as analogous to majority of programming (scripting) languages where you use the same assignment operator for both variable creation and updating, you should use the same HTTP method.<br/>Also, you'll avoid discussions about what is entity creation and update, esp. in scenarios where you want to allow creation and updates of sub-entities, where either of those can be viewed as update of the entity itself.<br/>Also, note that often REST is not supposed to allow access to sub-entities, but it makes life so much easier, and costs you less traffic.
 === Specific ===
@@ Line 21: / Line 34: @@
 == Disclaimer ==
-''This list is by no means supposed to represent any "standard view" of RESTful API's.''
+''This list is by no means supposed to represent any "standard view" of REST API's.''
 ''It does not represent opinions of any of the companies I work(ed) with.''
@@ Line 27: / Line 40: @@
 ''It is my personal checklist when designing interfaces. Many points depend only on your taste.''
-''Some of the opinions are even "not really RESTful" but make life easier for you as backend dev, or for your consumers.''
+''Some of the opinions are even "not really REST" but make life easier for either you as backend dev, or for your consumers, or both.''