Difference between revisions of "Short Notes on RESTful APIs"
(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...") |
|||
| Line 1: | Line 1: | ||
'''WIP - check for updates later.''' | '''WIP - check for updates later.''' | ||
| + | |||
| + | This section is about RESTful Web-based API's. | ||
Take this section with a pinch of salt. Also, see [[#Disclaimer|Disclaimer]]. | Take this section with a pinch of salt. Also, see [[#Disclaimer|Disclaimer]]. | ||
| Line 5: | Line 7: | ||
== What is RESTful? == | == What is RESTful? == | ||
| − | There is no standard for what | + | 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. |
| + | |||
| + | '''Representational state transfer (REST)''' is a way to create, read, update or delete information on a server using simple HTTP calls. | ||
| + | |||
| + | REST has strict separation of ''clients'' and ''servers'', by a uniform interface. | ||
| + | |||
| + | REST is ''stateless'' - each request from any client contains all the information necessary to service the request, and session state is held in the client. Important exception to this rule is authentication session that is stored on servers. | ||
| + | |||
| + | REST is ''cacheable''. Responses must therefore, implicitly or explicitly, define themselves as cacheable, or not, to prevent clients reusing state or inappropriate data in response to further requests. Well-managed caching partially or completely eliminates some client–server interactions, further improving scalability and performance. | ||
| − | + | REST has a ''uniform interface'': | |
| + | * ''Resources/entities'' are ''uniquely identified'' by URI's.<br/>The resources themselves are conceptually separate from the representations that are returned to the client (JSON, XML, ...). | ||
| + | * Client which holds such representation of a resource (including any metadata attached), it has ''enough information'' to modify or delete this resource. | ||
| + | * Each message includes ''enough information'' to describe how to process the message. | ||
== Interface Layout == | == Interface Layout == | ||
| Line 15: | Line 28: | ||
=== General === | === General === | ||
| − | * '''''Use POST for both entity creation and update.'''''<br/>Typically, | + | * '''''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 === | === Specific === | ||
| Line 21: | Line 34: | ||
== Disclaimer == | == Disclaimer == | ||
| − | ''This list is by no means supposed to represent any "standard view" of | + | ''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.'' | ''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.'' | ''It is my personal checklist when designing interfaces. Many points depend only on your taste.'' | ||
| − | ''Some of the opinions are even "not really | + | ''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.'' |
Revision as of 21:43, 28 June 2014
WIP - check for updates later.
This section is about RESTful Web-based API's.
Take this section with a pinch of salt. Also, see Disclaimer.
Contents
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.
Representational state transfer (REST) is a way to create, read, update or delete information on a server using simple HTTP calls.
REST has strict separation of clients and servers, by a uniform interface.
REST is stateless - each request from any client contains all the information necessary to service the request, and session state is held in the client. Important exception to this rule is authentication session that is stored on servers.
REST is cacheable. Responses must therefore, implicitly or explicitly, define themselves as cacheable, or not, to prevent clients reusing state or inappropriate data in response to further requests. Well-managed caching partially or completely eliminates some client–server interactions, further improving scalability and performance.
REST has a uniform interface:
- Resources/entities are uniquely identified by URI's.
The resources themselves are conceptually separate from the representations that are returned to the client (JSON, XML, ...). - Client which holds such representation of a resource (including any metadata attached), it has enough information to modify or delete this resource.
- Each message includes enough information to describe how to process the message.
Interface Layout
Interface Recommendations
General
- Use POST for both entity creation and update.
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.
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.
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
Disclaimer
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.
It is my personal checklist when designing interfaces. Many points depend only on your taste.
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.
