REST - Strategies for reducing requests while maintaining control - rest

Question

Say I want to model the relationship of IP Address and ports in a RESTful manner. An IP address contains many ports, while a port can only have one IP Address. Additionally an IP Address is unique in this domain by it's address, while a port is unique by it's port number within it's IP address.
What are the potential strategies to model this? I can think of three that all have advantages and disadvantages.
Separate Resources
Maintain completely separate resources of the two and represent the relationship through the URL structure and allow discovery through links.
GET .../ipaddress/{address}/
{
"ipaddress": "1.2.3.4",
"ipversion": "v4",
"links": [
{
"rel": "port"
"link": "/ipaddress/1.2.3.4/ports/1234"
},
{
"rel": "port"
"link": "/ipaddress/1.2.3.4/ports/1235"
},
{
"rel": "port"
"link": "/ipaddress/1.2.3.4/ports/1236"
}
]
}
GET .../ipaddress/{address}/port/{portnumber}
{
"port":1234,
"protocol":"unknown"
...other data here
}
Advantages
Logical representation of the resources that maps to the problem precisely.
Allows HTTP methods such as GET/POST/PUT/DELETE to be applied to not only an IP Address, but to a port within an IP Address.
Disadvantages
To retrieve all ports for an IP Address, I have to issue N + 1 requests. One request for the IP address to obtain links to all the ports and then N subsequent requests for each port resource.
Embedded Resources
Embed all port objects within the IP Address object.
GET .../ipaddress/{id}/
{
"ipaddress": "1.2.3.4",
"ipversion": "v4",
"ports": [
{
"port": 1234,
"protocol": "unknown",
otherdata....
},
{
"port": 1235,
"protocol": "unknown"
otherdata....
},
{
"port": 1234,
"protocol": "unknown"
otherdata....
}
]
}
Advantages
Can retrieve all port objects for an IP address with a single request.
Disadvantages
Can no longer issue a separate request to manipulate a port object. For example, how would you delete a single port from an IPAddress? I could issue a PUT request replacing the entire IP Address with the port removed or do some kind of delta but that seems clumsy.
Could potentially lead to a large set of data, say for example if the port object contained additional information about the application that opened it.
Hybrid Approach
Create separate resources, but within the link object in ipaddress, embed some data from that resource, in this case the port number.
GET .../ipaddress/{id}
{
"ipaddress": "1.2.3.4",
"ipversion": "v4",
"links": [
{
"port": 1234,
"rel": "port",
"link": "/ipaddress/1.2.3.4/ports/3"
},
{
"port": 1235,
"rel": "port",
"link": "/ipaddress/1.2.3.4/ports/3"
},
{
"port": 1236,
"rel": "port",
"link": "/ipaddress/1.2.3.4/ports/3"
}
] }
GET .../ipaddress/{id}/port/{portnumber}
Remains the same as the first example.
Advantages
Allows for some data to be obtained in a single request.
Allows me to issue GET/PUT/POST/DEL requires to a URI that represents a port.
Disadvantages
I have explicitly chosen what data to represent in the "link summary". If the client wants to know a list of all protocols for all ports they still have to perform N+1 requests.
I believe things like JSON+HAL use the hybrid approach, in that they have embedded links to other resources that contain data. But does the client have a choice of what is displayed?
If I don't use any embedded data I end up with too many requests and if I embed everything I end up without the fine grained control of being able to manipulate sub-resources. Are there any other modelling alternatives?
I know this is quite a trivial example as port doesn't have a lot of data in it. But this could be applied to any two objects with a dependent relationship.
Thanks

Answer 1

Use HAL+JSON embedded resources with their own link and a field filter in the queryString.
GET /ipaddress/1.2.3.4?fields="ipaddress,inversion,ports:[port,protocol,otherdata]"
{
"ipaddress": "1.2.3.4",
"ipversion": "v4",
"_embedded": {
"ports": {
"items": [
{
"port": 1234,
"protocol": "unknown",
otherdata....
"_links": {
"self": {
"href": "/ipaddress/1.2.3.4/ports/1234"
}
}
},
{
"port": 1235,
"protocol": "unknown"
otherdata....
"_links": {
"self": {
"href": "/ipaddress/1.2.3.4/ports/1235"
}
}
},
...
],
"_links": {
"self": {
"href": "/ipaddress/1.2.3.4/ports"
}
}
}
},
"_links": {
"self": {
"href": "/ipaddress/1.2.3.4"
}
}
}
Btw. the current implementation depends only on your needs...
Yes the client has a choice, you can add metadata (like link relations, microdata, microformats etc...) to your media format, and you can ignore parts of the response. You can send back complex link with the results which can contain input fields and you can setup with them link parameters, like field filters in the queryString, etc... Yes, this will make implementation harder, you have to work with it a lot, but I guess you don't expect a complete code without any effort...
There are a lot of other media types, for example: JSON-LD, collection+json, siren, etc... you can check them if you want, maybe their approaches are better for you...