REST API, how to model resources that need to maintain a specific order
We are in the middle of developing a new feature for our API and we are stuck in a dilemma.
We have two different types of resources with a 1-N relationship. Views and layers. A view can contain multiple layers. A layer can only belong to one view. We stick with the fact that we need to maintain order for the layers in the view.
And we came up with two approaches:
First Approach: Linked List
Each layer knows about its previous layer. In the database, this is achieved by the presence of a "parent" field in the "Layers" table, which contains the identifier of another layer. The first layer will have a NULL "parent" set.
It then issues the following URIs via the API:
Create a
GET /Representations/{repID}/layers
gets all layers for presentation. The order can be worked out by going through all layers and looking at the Parent field.
POST /Representations/{repID}/layers
body: Label: (string) Parent: LayerId
Used to create and insert a layer at a specific position by specifying the parent in the request body. If you set the parent to NULL, the newly created layer will be the first layer in order. If you omit the Parent field, the newly created layer will be positioned at the bottom of the order. The problem is that in the response, we need to notify the api user that other layers have changed order due to the new insert.
Update
PUT /Representations/{repID}/layers/{layerId}
body: Label: (string) Parent: LayerId Again you can specify a new parent to reorder the layer, and again we will need to send some information about all the other layers that have changed.
Delete
DELETE /Representations/{repID}/layers/{layerId}
it is necessary to send some information about all other layers that have changed.
Second Approach: Layers Order as Own Resource
The idea is that the layers themselves have no concept of order. It's just a resource. Then you get a layerorder resource, which is responsible for storing the layer order information.
This way you will still have a CRUD function for the layers: GET - POST - PUT - DELETE
but if you want to know anything about your order, or want to change your order, you will use the following uri:
/Representation/{repId}/layersorder
This resource will only support two methods
GET /Representations/{repID}/layersorder
returns an ordered list of layer IDs in this view.
PUT /Representations/{repID}/layersorder
body: [] - Array of layer IDs in new order. Updates the order of the layers. you need to pass the layer array id in the new order as the request body. (for example [1,3,2,4,6,5])
according to the first approach, whenever you add or remove a layer you will need to notify the api user that another resource has been updated. In the first approach, which was a list of layers affected by the change, this approach finds the new layer order (layerorder resource).
I would like to hear opinions, as well as examples of similar situations and how you solved the problem.
thank.
source to share
I have experienced some of what you are describing.
When doing PUT / POST that affects the entity (or entities), I like to return the complete object after the change. Hopefully the return object is not massive, but if I were to use your API, with the first approach ... I would love to do a PUT / POST and update the layer, and then return the full view object with updated Layer information.
It's just easy for me to commit my changes and immediately start working in my code with the new structure. I would not like doing PUT / POST and then doing an extra GET to see the change.
For the second approach ... the more work I have to do to make the API call, the more frustrated I become. I'm not sure if I read this correctly, but to do a PUT with the second approach, it seems to me that I need to construct all the view and layer objects to update one piece of data. It would be unpleasant.
I would prefer the syntax of the first approach, but with the concepts of the second. In other words, this is the document I expect to see after PUT / POST / GET:
{
"type" : "Representation",
"id" : 1,
"layers" : [
{ "id" : 1, "name" : "the first layer", "order" : 1, "parent" : "" },
{ "id" : 2, "name" : "the second layer", "order" : 2, "parent" : 1 },
{ "id" : 3, "name" : "the third layer", "order" : 3, "parent" : 1 }
]
}
It is sorted for me already, so I don't need to do the job, but it also has information used to create the sort just in case. I did it using REST API and it seems to work great for users.
source to share