api-design

I'm writing a library for novice programmers so I'm trying to keep the API as clean as possible. One of the things my Library needs to do is perform some complex computations on a large collection of ints or longs. There are lots of scenarios and business objects that my users need to compute these values from, so I thought the best way would be to use streams to allow users to map business objects to IntStream or LongStream and then compute the computations inside of a collector. However IntStream and LongStream only have the 3 parameter collect method: collect(Supplier<R> supplier,

The wikipedia article about Law of Demeter says: The law can be stated simply as "use only one dot". However a simple example of a fluent interface may look like this: static void Main(string[] args) { new ZRLabs.Yael.Pipeline("cat.jpg") .Rotate(90) .Watermark("Monkey") .RoundCorners(100, Color.Bisque) .Save("test.png"); } So does this goes together? Well, the short definition of the law shortens it too much. The real "law" (in reality advice on good API design) basically says: Only access objects you created yourself, or were passed to you as an argument. Do not access objects indirectly

When designing resource hierarchies, when should one use sub-resources? I used to believe that when a resource could not exist without another, it should be represented as its sub-resource. I recently ran across this counter-example: An employee is uniquely identifiable across all companies. An employee's access control and life-cycle depend on the company. I modeled this as: /companies/{companyName}/employee/{employeeId} Notice, I don't need to look up the company in order to locate the employee, so should I? If I do, I'm paying a price to look up information I don't need. If I don't, this

Background: I am taking a class at my university called "Software Constraints". In the first lectures we were learning how to build good APIs. A good example we got of a really bad API function is the socket public static void Select(IList checkRead, IList checkWrite, IList checkError, int microseconds); in C#. The function receives 3 lists of sockets, and destroys them making the user have to clone all the sockets before feeding them into the Select() . It also has a timeout (in microseconds) which is an int, that sets the maximum time the server can wait for a socket. The limits of this is +

On SortedMap.subMap This is the API for SortedMap<K,V>.subMap : SortedMap<K,V> subMap(K fromKey, K toKey) : Returns a view of the portion of this map whose keys range from fromKey , inclusive, to toKey , exclusive. This inclusive lower bound, exclusive upper bound combo ("half-open range") is something that is prevalent in Java, and while it does have its benefits, it also has its quirks, as we shall soon see. The following snippet illustrates a simple usage of subMap : static <K,V> SortedMap<K,V> someSortOfSortedMap() { return Collections.synchronizedSortedMap(new TreeMap<K,V>()); } //...

Bearing in mind various quirks of the data types, and localization, what is the best way for a web service to communicate monetary values to and from applications? Is there a standard somewhere? My first thought was to simply use the number type. For example "amount": 1234.56 I have seen many arguments about issues with a lack of precision and rounding errors when using floating point data types for monetary calculations--however, we are just transmitting the value, not calculating, so that shouldn't matter. EventBrite's JSON currency specifications specify something like this: { "currency":

Possible Duplicates: Calculating large factorials in C++ Howto compute the factorial of x How do you implement the factorial function in C++? And by this I mean properly implement it using whatever argument checking and error handling logic is appropriate for a general purpose math library in C++. Recursive: unsigned int factorial(unsigned int n) { if (n == 0) return 1; return n * factorial(n - 1); } Iterative: unsigned int iter_factorial(unsigned int n) { unsigned int ret = 1; for(unsigned int i = 1; i <= n; ++i) ret *= i; return ret; } Compile time: template <int N> struct Factorial { enum {

I want to make my RESTful API very predictable. What is the best practice for deciding when to make a segmentation of data using the URI rather than by using query params. It makes sense to me that system parameters that support pagination, sorting, and grouping be after the '?' But what about fields like 'status' and 'region' or other attributes that segment your collection? If those are to be query params as well, what is the rule of thumb on knowing when to use path params? Best practice for RESTful API design is that path params are used to identify a specific resource or resources, while