what is best practice API design for creating multiple resources in a single request?

[#1]

We have requirements that call for creating a new grouping of pre-existing resources that must support very large groups. Calling a single 'group member' API multiple times seems to be a poor performance model. How can we design a good API that accepts a list of resource identifiers in a single call?

[#2 · Accepted solution]

If possible, you can send all of your resource ids in the body of your request and then use the Extract Variables policy to set a flow variable. If your backend target allows multiple resource ids to be processed in one API call, you can use a Javascript policy to modify the target url to include all of the resource ids in it. If the backend target allows processing of only one resource id at a time, you can use Node.js to iterate through the list of resource ids, making multiple calls as needed. An Apigee a127 proxy can be used to do this efficiently.

[#3]

This has been forwarded on to internal teams for a response and an answer will be posted as soon as we have something for you.

[#4 · Accepted solution]

If possible, you can send all of your resource ids in the body of your request and then use the Extract Variables policy to set a flow variable. If your backend target allows multiple resource ids to be processed in one API call, you can use a Javascript policy to modify the target url to include all of the resource ids in it. If the backend target allows processing of only one resource id at a time, you can use Node.js to iterate through the list of resource ids, making multiple calls as needed. An Apigee a127 proxy can be used to do this efficiently.

[#5 · Accepted solution]

Hi @Michael Leaning

Did you try creating a concept of "filters" in your API design?

Let's say you have a resource collections of geeks

/v1/geeks/

you can usually access one of the resources in the collection like below

/v1/geeks/{geek-id}

But you want to access a, update or operate on a group of the resources. One of the ways of doing it could be using a filter to get those resources. For the geek collection here is a couple of example:

/v1/geeks/?skill=python 

/v1/geeks/?skill=python&location=blr

EDIT: I did not notice that that the question was specifically about "create". A generic suggestion for creating a multiple resources would be to POST an array of resources to the base collection.

e.g.,

POST /v1/geeks/

[
  {
    "id": "geek1",
    "skill": "python",
    "location": "blr"
  },
  {
    "id": "geek2",
    "skill": "java",
    "location": "sfo"
  }
]

But here also there are potential issues of performance with very large payloads. So you better limit how many elements can be posted at once. And secondly how do you maintain the atomicity of the transaction. That is, if one the resources posted has a problem - do you create the rest of the resources or you reject ALL? Good discussion to have. Good luck.

[#6]

Michael, it would helpful to see something approximating the URL and payload design you have in mind as your starting point. Would you share your current best guess for the design? I