api-design

Writing an API to communicate with a device connected on Serial port

I am afraid that several terminologies in my question are wrong. Please bear with me and correct me wherever I am wrong. I have to write a library/program that will provide set of function to operate a card reader attached at Serial Port. Like to eject card that was inserted in it, user will simply have to call in his code, for example,...

Using annotation to ensure that value returned by method is not discarded

String in Java is immutable. The following snippet is, broadly speaking, "wrong". String s = "hello world!"; s.toUpperCase(); // "wrong"!! System.out.println(s); // still "hello world!"!!! Despite this being "wrong", the code compiles and runs, perhaps to the confusion of many beginners, who must either be told what the mistake is, ...

Best way to create REST API for long lasting tasks?

Suppose I have 2 servers. The first is a service that provides some computations, which can last long time (minutes to hours). The second server will use this service to have some data computed. I'm trying to design a REST API for the first server and so far so good. But I'd like to hear some opinion on how to model notifications whe...

Why is the Windows API less straight forward than other APIs?

The Windows APIs don't seem to me to be as straight forward as you might expect. To me, they are somewhat convoluted fashion? Is this is an effect of keeping backwards compatibility? Is Microsoft's main goal to push developers to higher level abstractions like ATL/MFC, VB, and/or .net? It's my first time using the Win32 API and calls...

Why does F#’s Collections.Seq module basically reimplement all the Enumerable extension methods?

Why does the Collections.Seq module have lots of methods that appear to be equivalent to extension methods declared in System.Linq.Enumerable? Why did the designers of F# feel the need to create a new namespace and new/different names for all of these instead of reusing what already exists in .NET? (If they needed some extra methods, wh...

REST API design: Tell the server to "refresh" a set of resources

We have a resource on a REST server ie /someResources/1 /someResources/2 /someResources/3 where "someResource" is a server representation of a distributed object far away. We want to tell the server to "refresh" its representation of that "distributed object" by looking at it out in the network & updating the server's cache ie we ca...

Is it normal practise to have getters which call private methods in API design?

Hi, Is it common, in API Design, to do something like this: public ReadOnlyCollection GetCollection { get { // Get's read only collection here... } } In the body of the get, this calls a private method that fills the collection. So I only expose one, consistent object to clients. The thing which confuses me is if it is right to make...

Why does Enumerable.ToLookup<>() return an ILookup<,> and not a Lookup<,>?

There is one method in Lookup<,> that is not in ILookup<,>: public IEnumerable<TResult> ApplyResultSelector<TResult>( Func<TKey, IEnumerable<TElement>, TResult> resultSelector); Why is the return type of Enumerable.ToLookup<>() declared to be ILookup<,> despite the fact that it always seems to return an instance of Lookup<,>? If t...

What is state space?

I am viewing this lecture (http://www.youtube.com/watch?v=aAb7hSCtvGw&amp;hl=nl) and at about 34 minutes, a bullet point on a slide is mentioned stating "document state space very carefully". What is state space? Why would I have to document it "very carefully"? Unfortunately, I have no sound on the machine I am posting from right now, ...

Best practises when designing an API

Hi, I am designing an internal API for a system I am writing. What are some best practises in API Design to think about? Thanks ...

How can I design a javascript API that allows for cross-domain scripting securely?

I like the way Google Maps' api is consumed, using a script include, but I'm worried: My api is "semi-private", that is, accessible over the internet but should allow for secure transmission of data and some kind of authentication. The data should remain private over the wire, and one consumer shouldn't be able to get at another's data....