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
17
votes
5 answers

Should an async API ever throw synchronously?

I'm writing a JavaScript function that makes an HTTP request and returns a promise for the result (but this question applies equally for a callback-based implementation). If I know immediately that the arguments supplied for the function are…
Jon M
  • 11,669
  • 3
  • 41
  • 47
16
votes
4 answers

Why would someone design a RESTful API with 'API' in the URI?

I just finished reading Restful Web Services and Nobody Understands REST or HTTP and am trying to design an API with a RESTful design. I've noticed a few patterns in API URI…
Jason Rikard
  • 1,329
  • 1
  • 14
  • 23
16
votes
1 answer

In Python dataclasses, why can an InitVar have default but not a default_factory?

In Python 3.7, I can create a dataclass with a defaulted InitVar just fine: from dataclasses import dataclass, InitVar, field @dataclass class Foo: seed: InitVar[str] = field(default='tomato') stored: str = field(init=False) def…
Jacobo de Vera
  • 1,863
  • 1
  • 16
  • 20
16
votes
1 answer

Is OAuth irrelevant when HTTPS is used?

I am designing a RESTful API which will always communicate over HTTPS. Is there any reason to use a scheme like OAuth when running over HTTPS? I am particularly interested whether or not aspects like HMAC-signed requests, nonces, and timestamps are…
John Cromartie
  • 4,184
  • 27
  • 32
16
votes
3 answers

Is it better to have 1 Lambda function per route? or 1 Lambda that handles child routes?

If I have an API that has the following routes POST /slack POST /slack/hook POST /slack/another-hook POST /slack/hook/nested Is it better to have 4 separate Lambda functions and 4 routes in the API Gateway? Or to have 1 Lambda for the root route…
9er
  • 1,604
  • 3
  • 20
  • 37
16
votes
5 answers

How can I design a javascript API that allows for cross-domain scripting securely?

I like the way Google Maps' api is consumed, using a script include, but I'm worried: My api is "semi-private", that is, accessible over the internet but should allow for secure transmission of data and some kind of authentication. The data should…
Chris McCall
  • 10,317
  • 8
  • 49
  • 80
16
votes
3 answers

Retrofitting void methods to return its argument to facilitate fluency: breaking change?

"API design is like sex: make one mistake and support it for the rest of your life" (Josh Bloch on twitter) There are many design mistakes in the Java library. Stack extends Vector (discussion), and we can't fix that without causing breakage. We…
polygenelubricants
  • 376,812
  • 128
  • 561
  • 623
15
votes
2 answers

What is the pythonic way to represent an Iterable that can be iterated over multiple times

I would like to get your advice on the most pythonic way to express the following function in python with type hints: I'd like to expose a function as part of a library that accepts an input argument and returns an output. The contract for the input…
Carsten
  • 468
  • 4
  • 16
15
votes
4 answers

Why doesn't C# LinkedList.RemoveFirst() return the removed value?

Is there some idiomatic, performance or design philosophy reason why C#'s LinkedList's RemoveFirst() and RemoveLast() operations don't return the value removed? Right now, if I want to read and remove the first value, I believe the incantation…
Dilum Ranatunga
  • 13,254
  • 3
  • 41
  • 52
15
votes
1 answer

How to implement handles for a CUDA driver API library?

Note: The question has been updated to address the questions that have been raised in the comments, and to emphasize that the core of the question is about the interdependencies between the Runtime- and Driver API The CUDA runtime libraries (like…
Marco13
  • 53,703
  • 9
  • 80
  • 159
15
votes
2 answers

Random high content download time in chrome?

We have an API which randomly takes high content download time in chrome, It works fine always in firefox and takes an only few ms. The response size is 20kb uncompressed and 4kb compressed. The same request also works fine using curl. Things that…
rajat
  • 3,415
  • 15
  • 56
  • 90
15
votes
1 answer

What HTTP response code to use for failed POST request?

What HTTP response code should be returned when a POST request was not successful and a request body was correctly formatted? For successful POST request i am using 201 - Created, but there is no equivalent not created code. I am thinking either…
mko
  • 6,638
  • 12
  • 67
  • 118
15
votes
3 answers

How to indicate C++ ownership of pointer

Let's say I have a class: class Scheduler { Scheduler(JobService *service); AddJob(JobID id, ISchedule *schedule); } The constructor takes a pointer to the service, but Scheduler does not take ownership of the service pointer. Service…
Sergei G
  • 1,561
  • 3
  • 18
  • 26
15
votes
2 answers

Link to another resource in a REST API: by its ID, or by its URL?

I am creating some APIs using apiary, so the language used is JSON. Let's assume I need to represent this resource: { "id" : 9, "name" : "test", "customer_id" : 12, "user_id" : 1, "store_id" : 3, "notes" : "Lorem ipsum…
MeV
  • 3,761
  • 11
  • 45
  • 78
14
votes
2 answers

How services generate and use public and secret API keys?

Google, Stripe and many other companies have public API key and Secret API key. It is easy to generate random strings but my question is, how can I generate public and secret keys, store them and use them properly? The public API key is to tell who…
HypeWolf
  • 750
  • 12
  • 29
1 2 3
…
99 100