I'm designing an API and I want to allow my users to combine a GET parameter with AND operators. What's the best way to do this?
Specifically I have a group_by parameter that gets passed to a Mongo backend. I want to allow users to group by multiple variables.
I can think of two ways:
?group_by=alpha&group_by=beta
or:
?group_by=alpha,beta
Is either one to be preferred? I've consulted a few API design references but no-one seems to have a view on this.
There is no strict preference. The advantage to the first approach is that many frameworks will turn group_by into an array or similar structure for you, whereas in the second approach you need to parse out the values yourself. The second approach is also less verbose, which may be relevant if your query string is particularly large.
You may also want to test with the first approach that the query strings always come into your framework in the order the client sent them. Some frameworks have a bug where that doesn't happen.
Related
I'm trying to use async-profiler to analyze Apache Spark performance, and I find that, even when codegen disabled, the majority of CPU time is spend in anonymous classes, such as Iterator$$anon$11.hasNext.
Is there a way I can get async-profiler to include outer class names for the objects containing the methods?
Or is there a way I can get the JVM to attach more meaningful names?
Or is there a way I can give names to anonymous classes?
The closest I've found to anyone ever even asking about this is from Finding a specific lambda noted in a Profiler, but that doesn't seem super helpful.
Thanks.
I've tried to look up ways to do this, but I'm coming up empty.
i first want to say that i'm beginner in ocaml. So i made a simple app that takes data from a json, does some calculations or replace some of them with arg from the command line, then writes another json with the new data and also replace those values in a html template and writes that too. You can see my project here https://github.com/ralcr/invoice-cmd/blob/master/invoice.ml
The question is how to deal with that amount of variables? In the languages i know i would probably repeat myself twice, but here are like 6 times. Thanks for any advice.
First of all, I would like to notice, that StackExchange code review is probably a better place to post such questions, as the question is more about a design rather than about the language.
I have two suggestions, on how to improve your code. The first one is to use string maps (or hashtables) to store your variables. Another is much more radical, is to rewrite the code in a more functional way.
Use maps
In your code, you're doing a lot of pouring the same water from one bucket into another, without doing actual work. The first thing that comes to mind, is whether it is necessary at all. When you parse JSON definitions into a set of variables, you do not actually reduce complexity or enforce any particular invariants. Basically, you're confusing data with code. These variables, are actually data that you're processing not a part of the logic of your application. So the first step would be to use string map, and store them in it. Then you can easily process a big set of variables with fold and map.
Use functions
Another approach is not to store the variables at all and express everything as stateless transformations on JSON data. Your application looks like a JSON processor, so I don't really see any reason why you should first read everything and store it in the memory, and then later produce the result. It is more natural to process data on the fly and express your logic as a set of small transformations. Try to split everything into small functions, so that each individual transformation can be easily understood. Then compose your transformation from smaller parts. This would be a functional style, where the flow of data is explicit.
Is there any performance or other difference between providing several filter queries as separate fq parameters versus providing a single one with all constraints joined with AND?
E.g. fq=field1:foo&fq=field2:bar vs. fq=(field1:foo) AND (field2:bar)
Obviously the first method is more readable and manageable, but I'm sending long queries (suboptimal, but there are reasons for that) via POST, and the library I use doesn't handle POST array parameters very well: they come out as fq[0]=...&fq[1]=... which is not recognised by Solr. Hence I consider joining everything into a single fq parameter to avoid that and wonder if that has any other consequences apart from being an ugly crutch.
Solr version is 4.5 if that matters
you will have the same result with the 2 queries:
E.g. fq=field1:foo&fq=field2:bar vs. fq=(field1:foo) AND (field2:bar)
but for performance matters you should prefer to split into many fq your request ! :) It has always been faster for me ! Let me also ask you to use solr Filters they are great to optimise the request speed! enjoy solr! :)
I've been using Object as a way to have a generic associative array (map/dictionary) since AS3/Flex seems to be very limited in this regard. But I really don't like it coming from a C++/Java/C# background. Is there a better way, some standard class I've not come across... is this even considered good/bad in AS3?
Yes, Actionscript uses Object as a generic associative container and is considered the standard way of doing this.
There is also a Dictionary class available, flash.utils.Dictionary.
The difference is that Dictionary can use any value as a key, including objects, while Object uses string keys. For most uses, Object is preferred as it is faster and covers the majority of use cases.
You can see the details on Object here: http://livedocs.adobe.com/flash/9.0/ActionScriptLangRefV3/Object.html
and Dictionary here: http://livedocs.adobe.com/flash/9.0/ActionScriptLangRefV3/flash/utils/Dictionary.html
and the differences between them here: http://livedocs.adobe.com/flex/3/html/help.html?content=10_Lists_of_data_4.html
I'm afraid there's no native alternative to Object or Dictionary for maps and other structures. As for standard, well, it depends on how one defines standard, but there are a couple of known libraries that you might like to check out if you look for Java style collections.
Like this one:
http://sibirjak.com/blog/collections/as3commons-collections/
Also, you could take a look at this question, that has links to a couple of ds libraries (including the above one).
Collections in Adobe Flex
I wouldn't say using Objects is either good or bad practice. In the general case they are faster than any Actionscript alternative (since they are native), but less featured. Sometimes the provided functionality is good enough. Sometimes, it's a bit bare-bones, so something more structured could help you getting rid of lower level details in your code and focusing in your "domain logic", so to speak.
In the end, all of these libraries implement their data structures through Objects, Dictionaries and Arrays (or Vectors). So, if the native objects are fine for your needs, I'd say go with them. On the other hand, if you find yourself basically re-writting, say, an ad-hoc Set, perhaps, using one of these libs would be a wise choice.
When I try to refactor my functions, for new needs, I stumble from time to time about the crucial question:
Shall I add another variable with a default value? Or shall I use only one array, where I´m able to add an additional variable without breaking the API?
Unless you need to support a flexible number of variables, I think it's best to explicitly identify each parameter. In most cases you can add an overloaded method that has a different signature to support the extra parameter while still supporting the original method signature. If you use an array for passing variables it just makes it too confusing for users of your API. Obviously there are some inputs that lend themselves to an array (a list of points in a polygon, a list of account IDs you wish to perform an action on, etc.) but if it's not a variable that you would reasonably expect to be an array or list, you should pass it into the method as a separate parameter.
Just like many questions in programming, the right answer is "it depends".
To take Javascript/jQuery as an example, one good rule of thumb is whether the parameter will be required each time the function is called or whether it is optional. For example, the main jQuery function itself requires an expression to determine what element(s) the operation will affect:
jQuery(expresssion)
It makes no sense to try to pass this parameter as part of an array as it will be required every time this function is called.
On the other hand, many jQuery plugins require several miscellaneous parameters that may be optional. By convention, these are passed as parameters via an 'options' array. As you said, this provides a nice interface as new parameters can be added without affecting the existing API. This makes the API clean as well since the user can ignore those options that are not applicable.
In general, when several parameters are involved, passing them as an array is a nice convention as many of them are certainly going to be optional. This would have helped clean up many WIN32 API's, although it is more difficult to deal with arrays in C/C++ than in Javascript.
It depends on the programming language used.
If you have a run-of-the-mill OO language, you should use an object that you can easily extend, if you are really concerned about API consistency.
If that doesn't matter that much, there is the option of changing the method signature and overloading the method with more / different parameters.
If your language doesn't support either and you want the API to be binary stable, use an array.
There are several considerations that must be made.
Where is the function used? - Only in code you created? One place or hundreds of places? The amount of work that will need to be done to maintain existing code is important. Remember to include the amount of time it will take to communicate to other programmers that may currently be using your function.
How critical is the new parameter? - Do you want to require it to be used? If it has a default value, will that default value break existing use of the function in any subtle ways?
Ease of comprehension - How many parameters are already passed into the function? The larger the number, the more confusing and error prone it will be. Code Complete recommends that you restrict the number of parameters to 7 or less. If you need more than that, you should try to abstract some or all of the related parameters into one object.
Other special considerations - Do you want to optimize your efforts for any special conditions such as code speed or size? Are there any special considerations that must be taken into account for your execution environment? Keep in mind your goals for the project and make sure you aren't working against them with whatever design choice you make.
In his book Code Complete, Steve McConnell decrees that a function should never have more than 7 arguments, and rarely even that many. He presents compelling arguments - that I can't cite from memory, alas.
Clean Code, more recently, advocates even fewer arguments.
So unless the number of things to pass is really small, they should be passed in an enveloping structure. If they're homogenous, an array. If not, then a reasonably lightweight object should be built for the purpose.
You should do neither. Just add the parameter and change all callers to supply the proper default value. The reason is that parameters with default values can only be at the end, and will not be able to add any more required parameters anywhere in the parameters list, without having a risk of misinterpretation.
These are the critical steps to disaster:
1. add one or two parameters with defaults
2. some callers will supply it, and some will rely on defaults.
[half a year passed]
3. add a required parameter (before them)
4. change all callers to accept the required parameter
5. get a phone call, or other event which will make you forget to change one of the instances in part#2
6. now your program compiles perfectly, but is invalid.
Unfortunately, in function call semantics we usually don't have a chance to say, by name, which value goes where.
Array is also not a proper solution. Array should be used as a connection of similar objects, upon which there's a uniform activity performed. As they say here, if it's worth refactoring, it's worth refactoring now.