Would this RESTful JSON response format be compliant with HATEOAS?
Working on a REST API for work, and came across an issue where I want to pass a value that represents a relationship but also a URL of that relationship so that it could be compliant with HATEOAS.
I think I've come up with an appropriate solution, but would like some confirmation from those with more knowledge then me.
Would this RESTful JSON response still be compliant with HATEOAS principles?
{
"employee":{
"empId":12345,
"fName":"Bubba",
"lName":"Gump",
"title":"Shrimp",
"reportsTo":54321,
"hateoas":{
"self":"http://www.bubbagumpshrimp.com/rest/Employees/12345",
"reportsTo":"http://www.bubbagumpshrimp.com/rest/Employees/54321",
"directReports":"http://www.bubbagumpshrimp.com/rest/Employees/?reportsTo=12345"
}
}
}
So what do you all think? Will that format work?
Based on the suggestion from @fumanchu below, this is the format I'll try using for now...
{
"employee":{
"empId":12345,
"fName":"Bubba",
"lName":"Gump",
"title":"Shrimp",
"reportsTo":54321,
"hateoas":{
"collection":"http://www.bubbagumpshrimp.com/rest/Employees/",
"self":"12345",
"reportsTo":"54321",
"directReports":"12345/DirectReports"
}
}
}
Thanks for the guidance!
It "works" but it's redundant. Once you have the URI's why keep the bare id's that communicate nothing about their semantics or how they are to be used? I'd recommend you try this instead:
{
"employee":{
"self":"http://www.bubbagumpshrimp.com/rest/Employees/12345",
"fName":"Bubba",
"lName":"Gump",
"title":"Shrimp",
"reportsTo":"http://www.bubbagumpshrimp.com/rest/Employees/54321",
"directReports":"http://www.bubbagumpshrimp.com/rest/Employees/12345/directReports"
}
}
(There's no reason to expose the "directReports" resource as "?reportsTo=12345". It's always better to identify it by its meaning than by its implementation.)
If you are in control of your API and/or media type (and you must be in order to tell your clients where to expect URI's since JSON doesn't define any), you can even shorten that by declaring that the "reportsTo", and "directReports" values are URI's which are relative to "self":
{
"employee":{
"self":"http://www.bubbagumpshrimp.com/rest/Employees/12345",
"fName":"Bubba",
"lName":"Gump",
"title":"Shrimp",
"reportsTo":"54321",
"directReports":"12345/directReports"
}
}