Tag Info

Hot answers tagged

85

Your example is broken. You shouldn't have json objects with duplicate keys. What you are looking for is an array with movie objects, like this: [ {"name": "movie1"}, {"name": "movie2"} ] This approach also answers your question. You should return an empty array when the query does not match: [] On the other hand, if you try to get a ...


69

Imagine you have to use someone else's code designed as about below: class Messy { String concat(String param, String str) { /* ... */ } boolean contains(String param, String s) { /* ... */ } boolean isEmpty(String param) { /* ... */ } boolean matches(String param, String regex) { /* ... */ } boolean ...


65

I'm not going to address the design problem - just the question of whether to do things "correctly" in a non-public API. it's just for me, so it's kind of like I'm protecting my own code from myself That's exactly the point. Maybe there's coders out there who remember the nuances of every class and method they ever wrote and never mistakenly call into ...


42

In your latter scheme, you keep verbs in the URLs of your resources. This should be avoided as the HTTP verbs should be used for that purpose. Embrace the underlying protocol instead of ignoring, duplicating or overriding it. Just look at DELETE /item/delete/:id, you place the same information twice in the same request. This is superfluous and should be ...


34

Usually I would return number of records in result as metadata. I am not sure if that is normal REST practice, but it is not much extra data, and it is very precise. Usually there is pagination for lots of services, it is impractical to return huge resultset at once. Personally I am annoyed when there is pagination for small result sets.. If it is empty, ...


32

It is generally true for any public API, yes. Once you expose an API to the public and people start to build applications that depend on that API, it becomes extremely difficult to change the API because doing so will break all those applications. That tends to be both a difficult technical problem and a difficult political problem. Of course, it is ...


29

Crockford has given an extensive presentation titled "An Inconvenient API: The Theory of the Dom" where he more or less explains his opinions on the DOM. It's longish (1h 18m), but as most Crockford's presentations it's quite enjoyable and educative. Cross browsers inconsistencies seems to be his main concern, and I agree it's the single most annoying ...


28

How about doing both? Have a "low level" (so to speak) API that exposes functions of the system and have another "layer" that exposes services that a client might want to do. This layer would use the necessary low level API's required but those are still exposed if the client wants them. UPDATE: To also include some of the great points and comments made ...


28

Your desire not to split it out into three method calls is completely understandable, but you do have other options besides boolean parameters. You could use enums: falconPeer.SetVisibility(JoinRequestOptions.Accept, "aerw3", DiscoveryRequestOptions.Reply); Or even a flags enum (if your language supports it): ...


27

The returning of null makes sense to me since manipulating a null string should result in a null string, not an error Well, that is your opinion. Others may argument that String operations on a null object, which does not contain a String, make no sense and hence should throw an Exception Why "Java designers" did or did not something is difficult to ...


25

Don't provide multiple ways to do the same thing - that will just confuse the API users. Having several names for the same things means you don't have a good name for it.


21

Null may be a valid value for an element of a list. Say your list contains elements which represent some optional data about a list of users and is stored in the same order as the users. If the extra data is populated then your list will contain the additional data otherwise the slot corresponding to a user will be null. (I'm sure there are better ...


21

Your question, as I understand it, seems to be based on an incorrect premise. Let me see if I can reconstruct the reasoning: The linked-to article describes how automatically-generated sequences exhibit a "lazy" behaviour, and shows how this can lead to a counter-intuitive result. Therefore I can detect whether a given instance of IEnumerable is going to ...


21

I usually follow some simple rules: Try to always program by contract. If a method is publicly available or receives input from the outside world, enforce some defensive measures (e.g. IllegalArgumentException). For everything else that is only accessible internally, use assertions (e.g. assert input != null). If a client is really into it, they will ...


19

This design decision appears mostly driven by naming. Name ArrayList suggests to reader a functionality similar to arrays - and it is natural for Java Collections Framework designers to expect that vast majority of API users will rely on it functioning similar to arrays. This in particular, involves treatment of null elements. API user knowing that below ...


17

You have to be careful to avoid adding new vocabulary just for the sake of your API. My favorite APIs explain things to me in vocabulary I already understand. Along those lines: Don't add too many abstractions on top of what you're building on. Keep it simple. I already have to think about about half-a-dozen layers of abstraction. Dont make me think about ...


17

It depends on how many fields you're talking about, and how they are used. Concrete is preferable for highly structured queries with only a few fields, but if the querying tends to be very free form, then the concrete approach quickly becomes unwieldy with more than three or four fields. On the other hand, it's very difficult to keep a generic API pure. ...


17

The whole of the Internet is built on conventions. We call them RFCs. While nobody will come and arrest you if you violate an RFC, you do run the risk that your service will not interoperate with the rest of the world. And if that happens, you run the risk of your startup not getting any customers, your business getting bad press, your stockholders ...


16

a last() method is just as easy as list.get(list.size()-1), just like there is no first() method or fifth() method. It isn't that hard to synthesize and is a specialization. You can also reverse() the list and list.get(0) which will give the last item. Things that are easy to do, usually don't get their own specialized methods. import java.util.ArrayList; ...


16

Why not UserExists(name, password)? I don't think it is necessary to mention in the name of the method that the name and password are the first and second parameters. I can see that looking up at the parameters. Furthermore, I don't know the language you're using, but by choosing a name without such indication you can have proper method overloading if you ...


16

An API should be as consistent as possible. Making the same call to the API should always do the same thing. Responding differently based on the client version would be unexpected and confusing. It may lead to subtle errors, as someone who upgrades a client would get different results and not know why. Of course, you can make functions that provide ...


16

While there can be exactly one max value in a collection, there can be more than item representing that value. E.g {1, 9, 2, 9, 0} has max value of 9, represented by both elements [1] and [3]. Note that not all collections support index access; e.g. a Set<Integer> can have a meaningful maximum but accessing an element by index makes no sense in it. ...


15

Defensive programming is a very good thing. Until it starts getting in the way of writing code. Then it's not such a good thing. Speaking a bit more pragmatically... It sounds like you're right at the edge of taking things too far. The challenge (and the answer to your question) lies in understanding what the business rules or requirements of the ...


14

The usual reason for deprecating a class or method is because it's difficult to use or has behavior that is no longer considered "good," not because it's been replaced with a more efficient implementation. For example, the java.util.Date class has a constructor that takes three integer values, for year, month, and day. On the surface, this seems a simple ...


14

What's wrong with the DOM? Aside from Java-inspired syntax (which Crockford has touched on), nothing. What's "wrong" applies partially to browser vendors; what's "wrong" applies to developers; what's "wrong" applies to ignorance. So, where to begin? Down the rabbit holeā€¦ Browser Vendors First off, browser vendors have fought competitively over decades ...


14

You should not forget that GET requests have some superior advantages over other solutions: 1) GET requests can be copied from the URL bar, they are digested by search engines, they are "friendly". Where "friendly" means that normally a GET request should not modify anything inside your application (idempotent). This is the standard case for a search. 2) ...


13

Quote author is Joshua Bloch, the statement is from his Bumper-Sticker API Design article: Public APIs, like diamonds, are forever. You have one chance to get it right so give it your best. For more details on that, author refers readers to his conference session presentation, "How to Design a Good API and Why it Matters". Slide Why is API Design ...


12

API bloat is probably the answer. From my experience the only time I've needed this functionality a Queue or Stack was the correct data structure for the job having the appropriate method.


12

You're about to learn an important lesson about APIs. Any time you find yourself saying "I need something special that shouldn't be available to others", you're wrong. That's especially true when it comes to identification and authentication.



Only top voted, non community-wiki answers of a minimum length are eligible