HATEOAS implementation using Apigee

[santosh_ghalsas]

Hi All,

I wanted to know if anyone has done HATEOAS implementation using Apigee and what points have been considered while doing this. Basic things that I want to clarify are

1. The logic to determine next steps/actions(for adding respective hyperlinks in the response) should be implemented at Apigee layer or that info should come from some backend and only the rendering of final response should be done by Apigee?

2. How flexible should the hyperlinks provided with the response be in order to help API consumer to use them in the web app/mobile app?

Please help and provide any samples available on this to refer for more details.

Thanks,

Santosh

[#2 · Accepted solution]

I have written multiple applications behind Apigee Edge proxies that include lots of links. Those could be described as HATEOAS applications, depending on your interpretation of that term. The approach I took was to do most of the work in the 'target' application. I relied on my Apigee proxies for routing, security, monitoring, rate limiting and other qualities-of-service, but not for linking. My back-end databases are full of relationships expressed as foreign keys. My mid-tier object model parallels the data — it is full of corresponding "links" between the objects. When I produce JSON from these objects, the JSON is also full of links. I also produce HTML from the same objects — also full of links. The process works in reverse for input.

I am aware that some people attempt to 'inject' links into JSON that doesn't have them in a front-end tier (or proxy, if you like). I have not tried this. There are also schemes for inferring links that are not in the data from meta-data. Neither of these approaches appeals to me — they seem like band-aids over an underlying defect. I prefer to make sure that the JSON produced by the application has the links in the first place. I understand that you cannot always change the target application — maybe you don't even own it — so these band-aids can be important in some circumstances.

When you are writing Edge proxies that front-end an application whose request and response bodies include links, you need to be careful to preserve the original URL paths in the proxy. In other words the proxy should work like a true internet transparent proxy that does not change the URL, especially the path portion. If you change the URL paths in the proxy, the proxy will also have to find and fix up all the incoming and outgoing links in the bodies of the requests and responses, which is complex and error-prone.

[#3 · Accepted solution]

I have written multiple applications behind Apigee Edge proxies that include lots of links. Those could be described as HATEOAS applications, depending on your interpretation of that term. The approach I took was to do most of the work in the 'target' application. I relied on my Apigee proxies for routing, security, monitoring, rate limiting and other qualities-of-service, but not for linking. My back-end databases are full of relationships expressed as foreign keys. My mid-tier object model parallels the data — it is full of corresponding "links" between the objects. When I produce JSON from these objects, the JSON is also full of links. I also produce HTML from the same objects — also full of links. The process works in reverse for input.

I am aware that some people attempt to 'inject' links into JSON that doesn't have them in a front-end tier (or proxy, if you like). I have not tried this. There are also schemes for inferring links that are not in the data from meta-data. Neither of these approaches appeals to me — they seem like band-aids over an underlying defect. I prefer to make sure that the JSON produced by the application has the links in the first place. I understand that you cannot always change the target application — maybe you don't even own it — so these band-aids can be important in some circumstances.

When you are writing Edge proxies that front-end an application whose request and response bodies include links, you need to be careful to preserve the original URL paths in the proxy. In other words the proxy should work like a true internet transparent proxy that does not change the URL, especially the path portion. If you change the URL paths in the proxy, the proxy will also have to find and fix up all the incoming and outgoing links in the bodies of the requests and responses, which is complex and error-prone.

[shivaspksiva · Accepted solution]

1. The logic to determine next steps/actions(for adding respective hyperlinks in the response) should be implemented at Apigee layer or that info should come from some backend and only the rendering of final response should be done by Apigee?

>> If your backend is already implementing HAL/HATEOAS and you are only enriching the security / functionality in APIGEE layer then no need to re-invent the wheel, that's the best this possible.

If your backend services are non HAL/ HATEOAS then you may have to create the representations on APIGEE layer and these can be done in many different ways considering the wide range of APIGEE policies available. This is also a tedious task considering the flexibility that client may follow links to related resources, without hard wiring URIs in the client code, The backend may include some links conditionally, depending on the state and the business rules.

The client developer has to know both the semantics of ‘actions’ and what to do with it (which http method? what payload). These details have to be documented in a human readable way. HAL gives no guidance about that. Other hypermedia specifications like SIREN try to give an answer.

Reference APIs:

1. https://developer.paypal.com/docs/api/overview/#hateoas-links
2. http://stateless.co/hal_specification.html

2. How flexible should the hyperlinks provided with the response be in order to help API consumer to use them in the web app/mobile app?

>> Depends on how you design you API consumer, as you know the heavy lifting and intelligence is now on the Consumer end.

This is a good example of HAL for a BOOK resource, see the set of actions you will realize that API consumer can pick the URL based on the action it needs to perform.

This is from the following link: https://opencredo.com/hal-hypermedia-api-spring-hateoas/

{
   "isbn": "0321127420",
   "title": "Patterns of Enterprise Application Architecture",
   "available": 1,
   "_links": {
       "self": {
           "href": "http://localhost:8080/books/0321127420"
       },
       "purchase": {
           "href": "http://localhost:8080/books/0321127420/purchase"
       },
       "borrow": {
           "href": "http://localhost:8080/books/0321127420/borrow-a-copy"
       },
       "return": {
           "href": "http://localhost:8080/books/0321127420/return-a-copy"
       },
       "authors": [
           {
               "href": "http://localhost:8080/authors/martin_fowler"
           },
           {
               "href": "http://localhost:8080/authors/kendall_scott"
           }
       ],
       "publisher": {
           "href": "http://localhost:8080/publishers/2"
       }
   }
}

Thanks.

[santosh_ghalsas]

Hi @Martin , @shivaspk ,

Thank you for your inputs. I will look at these points and will come back if I need any more info.

Regards,

Santosh