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
37
votes
6 answers

Why can't AtomicBoolean be a replacement for Boolean?

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…
Brooks
  • 7,099
  • 6
  • 51
  • 82
37
votes
1 answer

Identify item by either an ID or a slug in a RESTful API

I'm currently designing an API and I came a cross a little problem: How should a URL of a RESTful API look like when you should be able to identify an item by either an ID or a slug? I could think of three options: GET /items/ GET…
Claudio Albertin
  • 2,076
  • 4
  • 18
  • 20
36
votes
5 answers

What is the standard for formatting currency values in JSON?

Bearing in mind various quirks of the data types, and localization, what is the best way for a web service to communicate monetary values to and from applications? Is there a standard somewhere? My first thought was to simply use the number type.…
Chad Schultz
  • 7,770
  • 6
  • 57
  • 96
36
votes
2 answers

404 Not Found or Bad Request?

Let's say that we have the following REST call: GET api/companies/5 (get company with id 5) If company '5' doesn't exist, we would typically return a 404 Not Found response. But now, let's take this call: GET api/companies/5/invoices/10 (get…
Dave New
  • 38,496
  • 59
  • 215
  • 394
36
votes
4 answers

find-or-create idiom in REST API design?

say we have a 'user' resource with unique constraint on 'name'. how would you design a REST API to handle a find-or-create (by name) use case? I see the following options: option 1: multiple requests client: POST /user {"name":"bob"} server: HTTP…
Nikita
  • 6,019
  • 8
  • 45
  • 54
34
votes
7 answers

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,…
polygenelubricants
  • 376,812
  • 128
  • 561
  • 623
34
votes
3 answers

When do I define objective-c methods?

I'm learning Objective-C, and have a C/C++ background. In object-oriented C++, you always need to declare your method before you define (implement) it, even if it is declared in the parent class. In procedural-style C, IIRC, you can get away…
Clinton Blackmore
  • 2,427
  • 2
  • 24
  • 31
33
votes
5 answers

Why don't primitive Stream have collect(Collector)?

I'm writing a library for novice programmers so I'm trying to keep the API as clean as possible. One of the things my Library needs to do is perform some complex computations on a large collection of ints or longs. There are lots of scenarios and…
dkatzel
  • 31,188
  • 3
  • 63
  • 67
31
votes
2 answers

Offset pagination vs Cursor pagination

I am studying about pagination and I have some questions. What is the difference between two approches? Best use-case for a cursor based pagination? Can cursor based pagination go to a specific page? Can cursor based pagination go back to the…
MINJA KIM
  • 876
  • 1
  • 8
  • 22
31
votes
9 answers

How to avoid repeating business logic between client and server?

As the needs of web apps have grown, I have found myself writing more and more API driven web applications. I use frameworks like AngularJS to build rich web clients that communicate with these APIs. Currently I am using PHP (Lumen or Laravel) for…
Roeland
  • 3,698
  • 7
  • 46
  • 62
29
votes
4 answers

RESTful API routes design: nested vs. non-nested

My question is about the advantages of nesting resources when building URLs for API purposes. Consider the following two alternatives for accessing an employee resource: /api/employees?department=1 # flat Vs. /api/departments/1/employees #…
Ernesto
  • 3,837
  • 6
  • 35
  • 56
27
votes
7 answers

What's the point of DSLs / fluent interfaces

I was recently watching a webcast about how to create a fluent DSL and I have to admit, I don't understand the reasons why one would use such an approach (at least for the given example). The webcast presented an image resizing class, that allows…
M4N
  • 94,805
  • 45
  • 217
  • 260
25
votes
2 answers

C# Generics: If T is a return type, can it also be void? How can I combine these interfaces together?

I have the following interface that returns the generic parameter of type T using a callback... public interface IDoWork { T DoWork(); } however I also have the following interface as well, but it won't invoke a callback since it returns…
makerofthings7
  • 60,103
  • 53
  • 215
  • 448
24
votes
1 answer

Is there a design reason why std::set doesnt have front and back member functions?

I know I can use *s.begin(), but same argument can be used for vector, which has front/back often I use the ordered property of set/map to get "smallest" element/key - ofc the fact that I do it is not the reason to have it, just a example :) Here…
NoSenseEtAl
  • 28,205
  • 28
  • 128
  • 277
23
votes
1 answer

How should protocol/implementation pairs be adjusted for the Swift API design guidelines?

In the new Swift API design guidelines, the commonly-used Type suffix for protocols is being dropped. While this is easy to do for protocols that are stand-alone (SequenceType becomes Sequence), I'm not sure how to update my APIs in which a protocol…
JHZ
  • 1,158
  • 1
  • 10
  • 15
1 2
3
…
99 100