From 5e98df13d292e275cd864ef36f1eecdc8afdcc9a Mon Sep 17 00:00:00 2001 From: Rogerio Bernardo Date: Sun, 19 Apr 2020 12:48:38 -0300 Subject: [PATCH 1/6] Fix HATEOAS reference and definition Previous reference and definition wrongly assumed HTML as mandatory for HATEOAS, where in fact Hypermedia is. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 293b8ac5..fd30c8f3 100644 --- a/README.md +++ b/README.md @@ -1505,8 +1505,8 @@ There are four qualities of a RESTful interface: * **Identify resources (URI in HTTP)** - use the same URI regardless of any operation. * **Change with representations (Verbs in HTTP)** - use verbs, headers, and body. -* **Self-descriptive error message (status response in HTTP)** - Use status codes, don't reinvent the wheel. -* **[HATEOAS](http://restcookbook.com/Basics/hateoas/) (HTML interface for HTTP)** - your web service should be fully accessible in a browser. +* **Self-descriptive error message (Status codes in HTTP)** - use status codes, don't reinvent the wheel. +* **[HATEOAS](https://en.wikipedia.org/wiki/HATEOAS) (Hypermedia in HTTP)** - provide dynamic application options throug hypermedia. Sample REST calls: From 8bd84d94c5c4d3dd152aeafddcffbb7df9f3b373 Mon Sep 17 00:00:00 2001 From: Rogerio Bernardo Date: Sun, 19 Apr 2020 12:49:44 -0300 Subject: [PATCH 2/6] Fix typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index fd30c8f3..a6ae719d 100644 --- a/README.md +++ b/README.md @@ -1506,7 +1506,7 @@ There are four qualities of a RESTful interface: * **Identify resources (URI in HTTP)** - use the same URI regardless of any operation. * **Change with representations (Verbs in HTTP)** - use verbs, headers, and body. * **Self-descriptive error message (Status codes in HTTP)** - use status codes, don't reinvent the wheel. -* **[HATEOAS](https://en.wikipedia.org/wiki/HATEOAS) (Hypermedia in HTTP)** - provide dynamic application options throug hypermedia. +* **[HATEOAS](https://en.wikipedia.org/wiki/HATEOAS) (Hypermedia in HTTP)** - provide dynamic application options through hypermedia. Sample REST calls: From 11a5136b8d4a36aa0c5284ba76d2b97d3a34b031 Mon Sep 17 00:00:00 2001 From: Rogerio Bernardo Date: Sun, 19 Apr 2020 13:05:47 -0300 Subject: [PATCH 3/6] Fix REST hierarchy disadvantage Previous definition assumed rest is only suited for simple hierarchies and presented a use case which can be easily expressed through query params or even an 'action' from a resource Replaced it with the indeed requisite for designing APIs, which is a solid understanding of the business, so relationships are well expressed. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a6ae719d..541340da 100644 --- a/README.md +++ b/README.md @@ -1521,7 +1521,7 @@ REST is focused on exposing data. It minimizes the coupling between client/serv #### Disadvantage(s): REST -* With REST being focused on exposing data, it might not be a good fit if resources are not naturally organized or accessed in a simple hierarchy. For example, returning all updated records from the past hour matching a particular set of events is not easily expressed as a path. With REST, it is likely to be implemented with a combination of URI path, query parameters, and possibly the request body. +* With REST being resource oriented, it demands a solid understanding of the business, so hierarchy and relationships between resources can be properly modeled. A poorly designed API is hard to evolve and misleads future clients implementations. * REST typically relies on a few verbs (GET, POST, PUT, DELETE, and PATCH) which sometimes doesn't fit your use case. For example, moving expired documents to the archive folder might not cleanly fit within these verbs. * Fetching complicated resources with nested hierarchies requires multiple round trips between the client and server to render single views, e.g. fetching content of a blog entry and the comments on that entry. For mobile applications operating in variable network conditions, these multiple roundtrips are highly undesirable. * Over time, more fields might be added to an API response and older clients will receive all new data fields, even those that they do not need, as a result, it bloats the payload size and leads to larger latencies. From bbc6989251d12d290c7f1ef0c9846110d6d1db5d Mon Sep 17 00:00:00 2001 From: Rogerio Bernardo Date: Sun, 19 Apr 2020 13:09:57 -0300 Subject: [PATCH 4/6] Removed verb misconcenption If an action outside CRUD is needed for a specific resource, it is usually expressed with an POST to an action. For instance, the previous example could be modelled as: POST /documents/archieveExpired --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index 541340da..8e3cc4ee 100644 --- a/README.md +++ b/README.md @@ -1522,7 +1522,6 @@ REST is focused on exposing data. It minimizes the coupling between client/serv #### Disadvantage(s): REST * With REST being resource oriented, it demands a solid understanding of the business, so hierarchy and relationships between resources can be properly modeled. A poorly designed API is hard to evolve and misleads future clients implementations. -* REST typically relies on a few verbs (GET, POST, PUT, DELETE, and PATCH) which sometimes doesn't fit your use case. For example, moving expired documents to the archive folder might not cleanly fit within these verbs. * Fetching complicated resources with nested hierarchies requires multiple round trips between the client and server to render single views, e.g. fetching content of a blog entry and the comments on that entry. For mobile applications operating in variable network conditions, these multiple roundtrips are highly undesirable. * Over time, more fields might be added to an API response and older clients will receive all new data fields, even those that they do not need, as a result, it bloats the payload size and leads to larger latencies. From 78a80e17e24ba8f1948625f87a7ecf438ccbeff3 Mon Sep 17 00:00:00 2001 From: Rogerio Bernardo Date: Sun, 19 Apr 2020 13:16:22 -0300 Subject: [PATCH 5/6] Add workaround to complex single view problem --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8e3cc4ee..5a2f78bf 100644 --- a/README.md +++ b/README.md @@ -1522,7 +1522,7 @@ REST is focused on exposing data. It minimizes the coupling between client/serv #### Disadvantage(s): REST * With REST being resource oriented, it demands a solid understanding of the business, so hierarchy and relationships between resources can be properly modeled. A poorly designed API is hard to evolve and misleads future clients implementations. -* Fetching complicated resources with nested hierarchies requires multiple round trips between the client and server to render single views, e.g. fetching content of a blog entry and the comments on that entry. For mobile applications operating in variable network conditions, these multiple roundtrips are highly undesirable. +* Fetching complicated resources with nested hierarchies requires multiple round trips between the client and server to render single views, e.g. fetching content of a blog entry and the comments on that entry. For mobile applications operating in variable network conditions, these multiple roundtrips are highly undesirable. In this case, additional endpoints or query parameters logic must be implemented to return aggregated data and reduce latency. * Over time, more fields might be added to an API response and older clients will receive all new data fields, even those that they do not need, as a result, it bloats the payload size and leads to larger latencies. ### RPC and REST calls comparison From 09276440257ff76bb8b396a3cb5f0aa2fbe3d52b Mon Sep 17 00:00:00 2001 From: Rogerio Bernardo Date: Sun, 19 Apr 2020 13:26:37 -0300 Subject: [PATCH 6/6] Rewrote resource change problem Add a more broad view of the problem derived from changing entities and business understanding evolving. Also add common workarounds. --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 5a2f78bf..a1611603 100644 --- a/README.md +++ b/README.md @@ -1523,7 +1523,8 @@ REST is focused on exposing data. It minimizes the coupling between client/serv * With REST being resource oriented, it demands a solid understanding of the business, so hierarchy and relationships between resources can be properly modeled. A poorly designed API is hard to evolve and misleads future clients implementations. * Fetching complicated resources with nested hierarchies requires multiple round trips between the client and server to render single views, e.g. fetching content of a blog entry and the comments on that entry. For mobile applications operating in variable network conditions, these multiple roundtrips are highly undesirable. In this case, additional endpoints or query parameters logic must be implemented to return aggregated data and reduce latency. -* Over time, more fields might be added to an API response and older clients will receive all new data fields, even those that they do not need, as a result, it bloats the payload size and leads to larger latencies. +* Over time, fields might be added, changed or even removed from an API response. Breaking changes should be versioned, which adds the complexity of maintaning multiple endpoints or headers versioning logic. Addition of fields can also lead to unecessary data being sent, which leads to the necessity of implementing response filtering logic, usually through query paramenters. + ### RPC and REST calls comparison