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
62
votes
7 answers

Do fluent interfaces violate the Law of Demeter?

The wikipedia article about Law of Demeter says: The law can be stated simply as "use only one dot". However a simple example of a fluent interface may look like this: static void Main(string[] args) { new ZRLabs.Yael.Pipeline("cat.jpg") …
Jakub Šturc
  • 35,201
  • 25
  • 90
  • 110
62
votes
4 answers

Why does the Duration class not have 'toSeconds()' method?

I was looking at the Duration class in Java 8 and noticed that it does not have: long toSeconds(); But it has all other toXXXXX() to get days, hours, minutes, millis, nanos. I do see a getSeconds() method that returns the number of seconds within…
Ali
  • 1,442
  • 1
  • 15
  • 29
61
votes
15 answers

What is the gold standard for website APIs? Twitter, Flickr, Facebook, etc

Seems like there are two categories of APIs for websites today. APIs which allow the functionality of the site to be extended like Facebook, Myspace, etc. These APIs seem to be very diverse. APIs which allow interaction with the existing site…
Jason
58
votes
1 answer

REST design for file uploads

I want to create a REST API for a file upload service that allows a user to: Open a session Upload a bunch of files Close the session And then later, come back and do things with the files they uploaded in a previous session. To facilitate dealing…
cdeszaq
  • 30,869
  • 25
  • 117
  • 173
56
votes
1 answer

API Endpoint Semantics

Is an API endpoint the 'method', like https://api.foursquare.com/v2/venues/ or the full URL including non-query-string parameters like https://api.foursquare.com/v2/venues/5104 In other words, are these two separate endpoints or considered the same…
Derek Dahmer
  • 14,865
  • 6
  • 36
  • 33
56
votes
6 answers

Rest API design with multiple unique ids

Currently, we are developing an API for our system and there are some resources that may have different kinds of identifiers. For example, there is a resource called orders, which may have an unique order number and also have an unique id. At the…
Indivon
  • 1,784
  • 2
  • 17
  • 32
56
votes
3 answers

Applying LIMIT and OFFSET to all queries in SQLAlchemy

I'm designing an API with SQLAlchemy (querying MySQL) and I would like to force all my queries to have page_size (LIMIT) and page_number (OFFSET) parameters. Is there a clean way of doing this with SQLAlchemy? Perhaps building a factory of some…
Rob Crowell
  • 1,447
  • 3
  • 15
  • 25
54
votes
8 answers

REST api versioning (only version the representation, not the resource itself)

I had a look at Best practices for API versioning?, but am not quite convinced of the answer, so I am question the versioning part again with a more specific example. I am having two URIs (one with versioning as part of the URI and one…
manuel aldana
  • 15,650
  • 9
  • 43
  • 50
53
votes
4 answers

Private class functions vs Functions in unnamed namespace

I've found myself that I tend not to have private class functions. If possible, all candidates to private class function rather I put in to unnamed namespace and pass all necessary information as function parameters. I don't have a sound explanation…
drumsta
  • 1,336
  • 2
  • 16
  • 27
45
votes
2 answers

Why there is no getFirst(iterable) method?

Iterables present two methods for getLast public static T getLast(Iterable iterable); public static T getLast(Iterable iterable, @Nullable T defaultValue); but only one for getFirst public static T getFirst(Iterable…
Stan Kurilin
  • 15,614
  • 21
  • 81
  • 132
45
votes
6 answers

When should we create our own Java exception classes?

From a good design/practice point of view, when should we create and use custom Java exception classes instead of the ones already predefined in Java? In some applications I see almost custom exception classes created, they make an effort to always…
PedroD
  • 5,670
  • 12
  • 46
  • 84
43
votes
4 answers

API design and jQuery

I have often heard that jQuery has made some poor API decisions. Although jQuery is not my favourite library it's the library I've used most often and I find it hard to point out specific mistakes in the API design or how it could have been…
Raynos
  • 166,823
  • 56
  • 351
  • 396
43
votes
6 answers

Why Java does not allow overriding equals(Object) in an Enum?

I've noticed that the following snippet... @Override public boolean equals(Object otherObject) { ... } ...is not allowed for an Enum, since the method equals(Object x) is defined as final in Enum. Why is this so? I cannot think of any use case…
Ashwin Prabhu
  • 9,285
  • 5
  • 49
  • 82
42
votes
2 answers

Should paging be zero indexed within an API?

When implementing a Rest API, with parameters for paging, should paging be zero indexed or start at 1. The parameters would be Page, and PageSize. For me, it makes sense to start at 1, since we are talking about pages
The Applicationist
  • 485
  • 1
  • 4
  • 12
39
votes
5 answers

REST API Design: Nested Collection vs. New Root

This question is about optimal REST API design and a problem I'm facing to choose between nested resources and root level collections. To demonstrate the concept, suppose I have collections City, Business, and Employees. A typical API may be…
Alex
  • 75,813
  • 86
  • 255
  • 348
1
2
3
…
99 100