REST API设计考虑因素

We are building this REST API layer for out partners where the architecture is something like this:

• We will have a bunch of REST API scripts built using PHP sitting on our storage server.
• A partner will hit our API with a transfer request
• We will fetch the customer data files related to that transfer request and push them to the partner's server.

The problem we are having is with the data files being requested. One transfer request can can ask for hundreds of data files.

Ideally we would prefer getting a single request from the partner for the transfer. (One request that will have all the data files to be transferred).

The other way is that each data file is a separate request and so one order of a hundred files will have 100 requests. This will have additional to and fro traffic as well as individual notification for each file which can be cumbersome.

So my question is - how to format a request to a REST API to retrieve a collection of over hundred objects? If I ask the partner to POST a txt file with the data file names it will not technically be REST, right? What is the ideal way to tackle this?

It sounds like you will need to handle the actual file transfers separately from the REST response, regardless of how you structure the actual API call. And I would suggest allowing an arbitrary number of files to be included in a single API call, this is, as you mention, less traffic to handle, and makes your API easier to use for the client. This does make for large payloads per request (for example a single call requesting a few thousands files would likely be up to 1MB of data), but you can fiddle with a cap on the maximum number of files per request as needed. So, your API will accept requests for file transfers, and then perhaps insert them in a queue of pending file transfers. This allows you to scale the API and the file transfer systems separately, managing the load on each as needed. For example if there is a slowdown in your transfer system, you can still accept requests via your REST API without overloading the system. A sample JSON structure would look something like this:

{
  files: [ { filepath: /path/to/file, height: 35, width: 100, type: image/jpeg  },
     { filepath: /path/to/file, height: 35, width: 100, type: image/jpeg  }, ]

}

Client should send all the image requests with in a single Json, XML or List. That can be parsed within the web API method and provide result to the caller.