设计数据驱动的JSON API

Question

I'm currently working on an API that accepts a large batch of data and performs a few different kinds of analysis on the data. Rather than forcing clients to pass in their data once for each sort of analysis they wish to perform, I thought it would make sense to offer just one API call and have that call accept the data and a list of actions (ie, analysis types) to perform. (This means that my API isn't RESTful, right?) I'll lose some clarity of function this way, but the gains in processing time will easily make up for that.

My question is about how the requests should be formatted in JSON. If the client just needed to POST an array of data elements and an array of actions to perform, then formatting would be easy. Unfortunately, a few of the analysis types have options that need to be set. I see a few ways forward.

1. Separate actions and options items:

    { 'data': [{'id': 1, 'content': 'blah'}, {'id': 2, 'content': 'blah}], 'actions': ['analysis_a', 'analysis_b', 'analysis_c'], 'options': {'option_c': 'blah'} } 

   Here it's up to the documentation to note that option_c only needs to be set if analysis_c is enabled.

2. Separate actions and options items, with options explicitly tied to an action:

    { 'data': [{'id': 1, 'content': 'blah'}, {'id': 2, 'content': 'blah}], 'actions': ['analysis_a', 'analysis_b', 'analysis_c'], 'options': {'analysis_c': {'option_c': 'blah'}} } 

3. Single actions/options item, with item acting as both a list and a dictionary:

    { 'data': [{'id': 1, 'content': 'blah'}, {'id': 2, 'content': 'blah}], 'actions': {'analysis_a': {}, 'analysis_b': {}, 'analysis_c': {'option_c': 'blah'}} } 

4. Single actions/options item with a bit more data structure clarity:

    { 'data': [{'id': 1, 'content': 'blah'}, {'id': 2, 'content': 'blah}], 'actions': [ {'action': 'analysis_a'}, {'action': 'analysis_b'}, {'action': 'analysis_c', 'options': {'option_c': 'blah'}} ] } 

Option #1 is probably my least favorite, but in the near future a few of our analysis types will require that the same option be set (necessarily with the same value), and that situation is a little easier to handle with Option #1.

I'm pretty torn, so any thoughts or suggestions would be much appreciated. Thanks!

Answer 1

I appreciate option #3 and option #4, because each action is self contained, which offers more clarity.

Whether choosing option #3 or option #4 depends on how you will perform the action, if the server have some operation that will retrieve a specific action from the action list by name. option #3 might be better(because option #4 requires you to iterate the array), if not, I think option #4 is better.