Stack Overflow
Stack Overflow

Questions tagged [api-design]

API design is the process of determining and exposing a set of consistent method signatures, return values, and documentation intended for use by other developers to allow programmatic access to data.

An API (Application Programming Interface) is what developers use to work with a specific software or platform. API design refers to those practices that lead to developing a good API. A good API design helps developers leverage the full power of your platform while being easy to use. A bad API design can hinder developers from utilizing the full power of your platform and in the worst case can drive developers away from your platform because of its difficulty.

API design shares many concepts with normal programming best practices. A few of these are separation of concerns and prevention of abstraction leakage.

References

2220 questions
541
votes
29 answers

What is the proper REST response code for a valid request but an empty data?

For example you run a GET request for users/9 but there is no user with id #9. Which is the best response code? 200 OK 202 Accepted 204 No Content 400 Bad Request 404 Not Found
IMB
  • 15,163
  • 19
  • 82
  • 140
466
votes
8 answers

When do I use path params vs. query params in a RESTful API?

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,…
cosbor11
  • 14,709
  • 10
  • 54
  • 69
411
votes
8 answers

What are best practices for REST nested resources?

As far as I can tell each individual resource should have only one canonical path. So in the following example what would good URL patterns be? Take for example a rest representation of Companies. In this hypothetical example, each company owns 0…
Wes
  • 6,697
  • 6
  • 34
  • 59
354
votes
12 answers

API pagination best practices

I'd love some some help handling a strange edge case with a paginated API I'm building. Like many APIs, this one paginates large results. If you query /foos, you'll get 100 results (i.e. foo #1-100), and a link to /foos?page=2 which should return…
2arrs2ells
  • 3,637
  • 3
  • 15
  • 12
248
votes
6 answers

Why are Java Streams once-off?

Unlike C#'s IEnumerable, where an execution pipeline can be executed as many times as we want, in Java a stream can be 'iterated' only once. Any call to a terminal operation closes the stream, rendering it unusable. This 'feature' takes away a lot…
Vitaliy
  • 8,044
  • 7
  • 38
  • 66
185
votes
6 answers

Delete multiple records using REST

What is the REST-ful way of deleting multiple items? My use case is that I have a Backbone Collection wherein I need to be able to delete multiple items at once. The options seem to be: Send a DELETE request for every single record (which seems…
Donald T
  • 10,234
  • 17
  • 63
  • 91
164
votes
8 answers

Call a Server-side Method on a Resource in a RESTful Way

Keep in mind I have a rudimentary understanding of REST. Let's say I have this URL: http://api.animals.com/v1/dogs/1/ And now, I want to make the server make the dog bark. Only the server knows how to do this. Let's say I want to have it run on a…
Kirk Ouimet
  • 27,280
  • 43
  • 127
  • 177
140
votes
4 answers

Why does String.valueOf(null) throw a NullPointerException?

according to the documentation, the method String.valueOf(Object obj) returns: if the argument is null, then a string equal to "null"; otherwise, the value of obj.toString() is returned. But how come when I try do…
user282886
  • 3,125
  • 8
  • 22
  • 11
114
votes
28 answers

GB English, or US English?

If you have an API, and you are a UK-based developer with a highly international audience, should your API be setColour() or setColor() (To take one word as a simple example.) UK-based engineers are often quite defensive about their 'correct'…
izb
  • 50,101
  • 39
  • 117
  • 168
113
votes
3 answers

Token Expired - JSON REST API - Error Code

I've got a JSON REST API. There is a handshake that will give you a token that is valid for 15 minutes. All calls you do within those 15 minutes should work ok. After the 15 minutes I am returning an error object (includes code, message, success =…
BuddyJoe
  • 69,735
  • 114
  • 291
  • 466
112
votes
3 answers

Why does int num = Integer.getInteger("123") throw NullPointerException?

The following code throws NullPointerException: int num = Integer.getInteger("123"); Is my compiler invoking getInteger on null since it's static? That doesn't make any sense! What's happening?
user282886
  • 3,125
  • 8
  • 22
  • 11
75
votes
5 answers

TypeORM: update item and return it

As far as I know, it's a best practice to return an item after it has been updated. TypeORM's updateById returns void, not the updated item though. My question: Is it possible to update and return the modified item in a single line? What I tried so…
sandrooco
  • 8,016
  • 9
  • 48
  • 86
68
votes
3 answers

Why is the Java date API (java.util.Date, .Calendar) such a mess?

As most people are painfully aware of by now, the Java API for handling calendar dates (specifically the classes java.util.Date and java.util.Calendar) are a terrible mess. Off the top of my head: Date is mutable Date represents a timestamp, not a…
sleske
  • 81,358
  • 34
  • 189
  • 227
68
votes
6 answers

RESTful design: when to use sub-resources?

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…
Gili
  • 86,244
  • 97
  • 390
  • 689
65
votes
13 answers

How do you define a good or bad API?

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…
fmsf
  • 36,317
  • 49
  • 147
  • 195
1
2 3
…
99 100