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
12
votes
11 answers

When is an API overengineered?

I despise working with overengineered APIs that don't make simple things simple. Nonetheless, I'm working on designing an API for an open-source library and I'm starting to feel that I'm falling into the overengineering trap. I really can't tell…
dsimcha
  • 67,514
  • 53
  • 213
  • 334
12
votes
3 answers

Designing an async API in Python

(Note: this question is strictly about the design of the API, not about how to implement it; i.e. I only care about what the client of my API sees here, not what I have to do to make it work.) In simple terms: I want to know the established pattern…
Pavel Minaev
  • 99,783
  • 25
  • 219
  • 289
12
votes
1 answer

Interior mutability abuse in API design?

My background in C++ makes me uncomfortable about interior mutability. The code below is my investigation around this topic. I agree that, from the borrow checker point of view, dealing with many references on every single struct which internal…
prog-fh
  • 13,492
  • 1
  • 15
  • 30
12
votes
1 answer

REST API Design - Single General Endpoint or Many Specific endpoints

This is a relatively subjective question, but I want to get other people's opinion nonetheless I am designing a REST Api that will be accessed by internal systems (a couple of clients apps at most). In general the API needs to update parameters of…
Kobek
  • 1,149
  • 6
  • 18
  • 40
12
votes
4 answers

Java API Design: NumberFormatException for Method that Parses a Semi-Numeric String?

I'm making a library that contains a few methods for parsing string dates and times. I am having difficulty deciding what exception those methods should throw when the string argument isn't parseable. I'm considering several options: 1. …
MB.
  • 7,365
  • 6
  • 42
  • 42
12
votes
3 answers

Creating C++ API Library

I'm trying to understand the correct way, or right approach, to provide a reasonably large C++ API for a non-open source project. I do not want to provide a "header only" library as the code base is fairly large and meant to be closed source. The…
humbleprogrammer
  • 121
  • 1
  • 1
  • 3
12
votes
3 answers

JSON API and CSRF

I'm developing a web API. authentication is through cookies. All endpoints receive parameters through JSON in the request body. Do I need to implement a CSRF token to protect them? How can this be exploitable? Is it possible to send JSON through a…
Pipe
  • 2,379
  • 2
  • 19
  • 33
12
votes
3 answers

Response to a PATCH request

Suppose I have an endpoint /api/todos and I make a PATCH request to change one of the todos. Does it ever make sense for my PATCH request to have in the response body the list of all of the todos? Is there any specification that I can read about…
A. Wong
  • 434
  • 1
  • 5
  • 16
12
votes
3 answers

Should a tag be it's own resource or a nested property?

I am at a crossroads deciding whether tags should be their own resource or a nested property of a note. This question touches a bit on RESTful design and database storage. Context: I have a note resource. Users can have many notes. Each note can…
dipole_moment
  • 5,266
  • 4
  • 39
  • 55
12
votes
3 answers

Unable to autoload constant API Controller in Rails 4

I'm creating a simple api endpoint in my Rails 4.2.6 app but am having problems with it. When I hit the url: http://lvh.me:9077/api/v1/grubs I receive the following error: Unable to autoload constant Api::V1::GrubsController, expected…
nulltek
  • 3,247
  • 9
  • 44
  • 94
12
votes
2 answers

Is there a defined strategy for versioning SignalR hubs, so that old JS code can continue to work?

I want to be able to make changes to the method signatures, names, etc on existing SignalR hubs. Is there a defined strategy for versioning SignalR hubs, so that old JS code can continue to work, without having to create a fresh newly named hub for…
David Pfeffer
  • 38,869
  • 30
  • 127
  • 202
12
votes
6 answers

Custom Collection vs Generic Collection for public methods

What are the framework design guidelines for exposing a custom collection vs generic one? e.g public class ImageCollection : Collection { ... } public class Product { public ImageCollection {get; set;} } VS public class Product { …
Anton P
12
votes
4 answers

(start, end) vs. (start, length) in API design

I've seen two alternative conventions used when specifying a range of indexes, e.g. subString(int startIndex, int length); vs. subString(int startIndex, int endIndex); They are obviously equivalent in terms of what you can do with them, the only…
mikera
  • 105,238
  • 25
  • 256
  • 415
12
votes
2 answers

CXF REST APIs Documentation using Swagger

According to Swagger's tutorial, seems swagger only support Jersey framework (See https://github.com/wordnik/swagger-core/wiki/java-jax-rs) Does anybody have experience on making swagger work with CXF JAX-RS implementation? Could you share your…
Dylan
  • 179
  • 2
  • 12
11
votes
3 answers

How to organize Python API module to make it neat?

I'm writing a Python library that represents some web API. Right now, my library directory looks close to this: __init__.py Account.py Order.py Category.py requests.py In __init__.py, I have something like this: from .Account import Account from…
Anonymouse
  • 385
  • 3
  • 16
1 2 3
…
99 100