Tag Info

Hot answers tagged

78

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 ...


62

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 ...


53

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 ...


31

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 ...


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

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, ...


26

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 ...


26

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 ...


20

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 ...


19

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 ...


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 ...


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

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. ...


15

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 ...


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

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 ...


13

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 ...


13

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 ...


13

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) ...


12

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

At the very least, the REST api needs to return an error code (e.g. 123) and/or an error key (e.g. "cannotRegister") which the application can then pick up in order to display a related message. This also helps when you're dealing with an application that is available in multiple languages. The app can then pick the related message from the appropriate ...


11

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; ...


11

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 ...


11

If you execute operation successfully, but it doesn't have anything to return, such as empty map {} or empty array [] I would prefer to respond with 204 response code, here is excerpt from HTTP Status Code Definitions spec: The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation. ...


11

Defensive coding is not just a good idea for public code. It's a great idea for any code that is not immediately thrown away. Sure, you know how it's supposed to be called now, but you have no idea how well you'll remember this six months from now when you come back to the project. Java's basic syntax gives you a lot of baked-in defense compared to a ...


10

A useful API has the following: Concise and thorough documentation. If I'm searching on how to implement a task, I'm able to find out if the API has the capability to do so, within a couple of minutes. This is achieved by the brevity of the text and the layout of the resource. The documentation provides examples on how to use it and also makes no ...


10

Actually, I don't believe that "consistency with platform" is a "minor" point in most cases. Quite to the contrary, you should design a library like others are likely to expect to use it. If the primary target audience for, or platform that is targetted by, your library uses bitfields, then you are probably better off using bitfields. That said, bitfields ...


10

If this is JSON, you should really consider returning an Array of objects. This has many advantages including that when you have no records it is an empty array. So when you have records, you would be returning: [ {"name": "Ghostbusters"}, {"name": "Indiana Jones"} ] And when you have no records, you would be returning: [ ...


9

Never trust user input, even if that user is an API consumer. Its your responsibility to maintain integrity in your data, their reponsibility to maintain theirs. If your code requires the clientID to be unique then check its unique before you save it. Trusting user input couples your code with theirs, when they have bugs on their system they can then ...



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