Creating an server-defined collection through the API?
49 views
Skip to first unread message
Julie C
Jan 13, 2018, 7:59:07 AM1/13/18
to API Craft
Hi all,
How might you go about modelling a REST request to create a collection of resources, where the elements in the collection are determined by complex application logic? In other words, the client knows generally the collection it wants to create, but the server knows the specific elements to put in the collection.
Example.
I have the following resources:
/items - describes a "thing" that a person might own. e.g. "house", "car"
/assets - describes the thing that a person possesses. e.g. "my house", "my car"
/tasks - describes a pre-defined task that a person needs to do to the item they own. e.g. "clean gutters", "change tires"
/todolist - relates tasks and items, in a realized kind of way. e.g. "clean my gutters", "change my tires"
To query the todolist related to an asset, we have:
GET /todolist?asset="my house"
It's easy enough to allow a client to add items to the todo list:
POST /todolist {asset:"my house", task: "clean gutters"}
One feature of our application is that we can automatically populate your todolist based on the state of your asset (your house has no gutters? we don't add that task to your todolist).
For a variety of reasons we do not populate that list immediately when you create the asset resource. Instead, there's an engine that wakes up periodically and looks for todolists that need initializing or updating. For some users, that isn't happening fast enough. But since the logic on how we relate these 3 resources to create the todolist is complex (and inappropriate to expose to clients), we are contemplating exposing the ability to trigger the engine to initialize their todolist on demand.
The first thought that occurs to me is something like
POST /todolist?asset="my house"
with no payload. Is that weird, given that we already have a different POST syntax on that resource?
How would you do it?
Cheers and thanks,
Julie
How might you go about modelling a REST request to create a collection of resources, where the elements in the collection are determined by complex application logic? In other words, the client knows generally the collection it wants to create, but the server knows the specific elements to put in the collection.
Example.
I have the following resources:
/items - describes a "thing" that a person might own. e.g. "house", "car"
/assets - describes the thing that a person possesses. e.g. "my house", "my car"
/tasks - describes a pre-defined task that a person needs to do to the item they own. e.g. "clean gutters", "change tires"
/todolist - relates tasks and items, in a realized kind of way. e.g. "clean my gutters", "change my tires"
To query the todolist related to an asset, we have:
GET /todolist?asset="my house"
It's easy enough to allow a client to add items to the todo list:
POST /todolist {asset:"my house", task: "clean gutters"}
One feature of our application is that we can automatically populate your todolist based on the state of your asset (your house has no gutters? we don't add that task to your todolist).
For a variety of reasons we do not populate that list immediately when you create the asset resource. Instead, there's an engine that wakes up periodically and looks for todolists that need initializing or updating. For some users, that isn't happening fast enough. But since the logic on how we relate these 3 resources to create the todolist is complex (and inappropriate to expose to clients), we are contemplating exposing the ability to trigger the engine to initialize their todolist on demand.
The first thought that occurs to me is something like
POST /todolist?asset="my house"
with no payload. Is that weird, given that we already have a different POST syntax on that resource?
How would you do it?
Cheers and thanks,
Julie
Lukas Rosenstock
Jan 16, 2018, 1:01:18 PM1/16/18
to api-...@googlegroups.com
Hello Julie,
requests to the same endpoints should always accept the same schema for the request body, so the example you suggest would be quite inconsistent:
It's easy enough to allow a client to add items to the todo list:
POST /todolist {asset:"my house", task: "clean gutters“}
The first thought that occurs to me is something like
POST /todolist?asset="my house"
What about simply using POST /todolist {asset:“my house“}?
It means that task would be optional but the format of the request stays the same.
If you want to make it more explicit you could use something like {asset:“my house“, create_tasks:true}.
Hope this helps.
Andrew B
Jan 17, 2018, 12:55:12 PM1/17/18
to API Craft
It sounds like you are exposing some aspects of an external resource (your todolist engine) so maybe you should give it it's own resource.
E.g POST /todolist/triggerRequests
Reply all
Reply to author
Forward
0 new messages