api-design

I'm revising code I did not write that uses JavaMail, and having a little trouble understanding why the JavaMail API is designed the way it is. I have the feeling that if I understood, I could be doing a better job. We call: transport = session.getTransport("smtp"); transport.connect(hostName, port, user, password); So why is Eclipse warning me that this: transport.send(message, message.getAllRecipients()); is a call to a static method? Why am I getting a Transport object and providing settings that are specific to it if I can't use that object to send the message? How does the Transport class

Is there naming convention for methods that return Stream? The only mention I found is this answer on S.O (last paragraph), but I don't see what is it based on. Since I wrote that paragraph I feel compelled to answer. :-) Suppose you have a class that represents an aggregation of things of a single type, and you want to return a Stream of them to the caller. If it's totally unambiguous as to what you're returning, you might just as well call the method stream() . There are a lot of methods in the JDK named stream() that return a stream of the obvious type. Sometimes what you're returning is

I am creating some APIs using apiary , so the language used is JSON. Let's assume I need to represent this resource: { "id" : 9, "name" : "test", "customer_id" : 12, "user_id" : 1, "store_id" : 3, "notes" : "Lorem ipsum example long text" } Is it correct to refer to other resources by their IDs ( 12 , 1 , 3 ), or I should specify the URL of these resources (i.e. /customers/12 , /users/1 , /stores/3 )? I am not using HATEOAS and I am a bit confused. stakx supports GoFundMonica DO include absolute entity URIs in your responses (such as /customers/12 or even http://www.example.com/customers/12 ).

Note: Although my particular context is Objective-C, my question actually transcends programming language choice. Also, I tagged it as "subjective" since someone is bound to complain otherwise, but I personally think it's almost entirely objective. Also, I'm aware of this related SO question , but since this was a bigger issue, I thought it better to make this a separate question. Please don't criticize the question without reading and understanding it fully. Thanks! Most of us are familiar with the dictionary abstract data type that stores key-value associations, whether we call it a map,

I am writing an .NET wrapper API for the Netflix API. At this point I can choose to represent URLs as either strings or URI objects. Seems to me there is a good case for both. So if you were using an API, which would you prefer? The below quote is from: Framework Design Guildelines I highly recommend this book to anyone developing frameworks on .Net Do use System.Uri to represent URI / URL data. (For Parameters, properties, and return values) System.Uri is a much safer and richer way of representing URIs. Extensive manipulation of URI-related data using plain strings has been shown to cause

Important note The focus of this question is on API endpoints that differentiate which resources are returned depending who authenticates , e.g. Alice gets resource A and B returned, and Bob gets resource X and Y. It is NOT about differentiating the representation of resources returned. All the endpoints return JSON representations of resources. Preface Please consider the following three potential API endpoint designs, all returning thing resources of a user. Endpoint A GET /things If authentication credentials for <user_x> are provided with the request, it returns thing resources that

The Oracle JDK Javadoc for AtomicBoolean states: https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/atomic/AtomicBoolean.html A boolean value that may be updated atomically. See the java.util.concurrent.atomic package specification for description of the properties of atomic variables. An AtomicBoolean is used in applications such as atomically updated flags, and cannot be used as a replacement for a Boolean. A colleague and I were trying to figure out a use-case where the AtomicBoolean can't be a substitute and the only thing we can think of is that there are methods the Boolean