Currently we have to make a new REST API at work. I want to have a clear and functional API (with HAL JSON, that is given). But my colleagues don’t like this, because they don’t like the design (the look and feel) of the HAL JSON responses. They just want an easy API with a nice design, so they want to ignore half of the HAL JSON specification. But a REST API don’t has to be easy and don’t need a fancy design, REST APIs are not for humans but for computers! How can I explain this to them?

Do you use the swagger Extension?

to be honest, your arguments would also not convince me in every situation. HAL seems to be great, thats for sure, but it comes with the use case why HAL should be used.

In my opinion HAL is great when you want to add functionality and the client is self learning the new structure. but then on the other hand it will fit the manual webpage approach more than an automated api approach where a machine must retrieve some detailed information. normally they can't cope with any dynamic changes. because you must somehow know where to look up your informations.

I don’t like HAL even, but it is predetermined by our architects. And I think if something is predetermined we should use it as it should be used.