I have been having a busy summer, but last week I went to a very cool APICraft conference. While it was about API’s in general, hypermedia API’s was the biggest topic. Here are some thoughts on it.
The conference was in downtown Detroit, and I was like whatever. But, my expectations were blown away, especially when there was a panel of 6 leading Hypermedia API media type creators. If you are not familiar with Hypermedia API’s, let me give you some back ground into what I am talking about:
This is why the conference was amazing, these guys are leading the way in semantic web api’s. What they talked about were subtle things. How to get adoption? What is the way to go? Why does this matter? I think the why this matters is the biggest issue facing hypermedia.
The reason why hypermedia matters is because the web is evolving over time. Unfortunately, to get any useful data out of the web, you have to read reams of documentation, at nauseum, to take advantage of all the cool api’s out there. What hypermedia api’s are trying to do is guide developers without loads of documentation. That’s it. Nothing special.
Some of the criticism behind hypermedia api’s is that it adds to your payload. While it can, it is important to note how the client using the API will become simpler. For instance, if the server can provide the proper options for the client, then I don’t have to code as much business logic into it. We are using HAL at Quicken, and I have seen the change that it has helped shape. When you give someone all the links that they can do, they will just put it on the screen for the user. After all, the user is the true person that will guide where to go for the API, not the client app. And yet, we spend so much time on the client app to make sure it is ready for all the scenarios, and yet our server already knows what scenarios it needs. Why not program the client to be as dumb as possible? Let’s get straight to the point and not add un-needed layers on top of a program.
As for the size concerns, the beauty of these API’s is that there are a bunch of standards. Just look above. Pick one that is right for your concerns. And these guys said it, if the size is bad, don’t use it. The case is in embedded systems; where you don’t have a lot of memory to work with. They would then suggest not using hypermedia API, or you could create a proxy that simplify the data for the embedded scenario.
We chose to adopt HAL on our team because it was simple and light, but also to get our foot in the door. The other issue with hypermedia API’s is that developers may not adhere to the standard. This is unfortunate, and if this is the case, you might as well not implement Hypermedia. But if you can, hold your guns and educate developers about the importance of it.
There was yet one more thing they strongly encouraged at the conference, and that was to spread the word. By this, I mean program Hypermedia API’s and educate people on them. So, as part of my due diligence, I decided to create an API for my website. In the API, you will be able to request any one of these 6 API’s to experiment with for your own learning. While at the time of writing this article, I will have to go back to work tomorrow, I hope to finish implementing all of these standards soon. You can check to see which standards I have implemented at /api or at /api/documentation to see what each brings to the table.
Currently, I have HAL and just a regular old json object that I am hosting, but stay tuned for more developments.