Questions tagged [api-design]
Application Programming Interface (API) Design discusses best practises for creating libraries intended for general purpose or public use.
1,170 questions
2
votes
3
answers
216
views
API Design: Should I explicitly check for and throw on nullptr parameters if I have full control?
Say I have the following header
#ifndef WINDOW_HPP
#define WINDOW_HPP
// includes...
namespace window
{
struct Window
{
GLFWwindow *handle = nullptr;
};
struct ...
user393053
0
votes
2
answers
216
views
Is exposing full backend entities to a Vue frontend a bad practice? A case for DTOs?
I am doing the frontend for a Java Spring backend. The project uses JavaFX for the front but I a migrating it for web usage (with VueJS). When I make an API call to retrieve an object, I am receiving ...
1
vote
1
answer
147
views
Should pagination metadata like totalCount be included in the ETag for cached paginated API responses?
I am currently rethinking my API response schema and caching strategy while implementing ETag-based caching for a paginated REST API (for example, listing places).
Each paginated response looks like ...
- 19
1
vote
3
answers
313
views
How to pass arguments of a complex search in RESTful API request params
I’m building an app that lets users manage data across multiple tables. I also expose an API so they can fetch their data and process it in external services.
I’d like to enhance the API to support ...
1
vote
2
answers
606
views
Is there anything that rest APIs can do that GraphQL still cannot do?
I just started learning about the specification, but I still have some doubts about why GraphQL simply hasn't replaced REST since it was created.
REST APIs are very inflexible and straightforward. ...
- 39
2
votes
1
answer
190
views
Serving several external APIs in Django + Angular application
I'm working on a web-based app that uses Django and Angular. This app uses several external APIs to fetch environmental data from different monitoring networks. We then use these data to perform ...
- 29
0
votes
1
answer
169
views
Microservice Architecture Design
I want to create one service that reads data from two databases and passes it to the customer devices. Is this an overall bad design decision? I think that since it is only read-only, it should be ...
- 121
2
votes
8
answers
553
views
Contract extensibility as it relates to enums and type unions
Say I have a contract returning a type:
type CreditCard = {
scheme: "Visa" | "Mastercard"
}
and later we decided to include Amex as card type, then making this change:
type ...
- 2,769
2
votes
1
answer
188
views
Should I split endpoints by parameter requirements?
Preface: This will not be available publicly or to third parties, so I am not concerned about users having the background knowledge to properly form GET requests. These are also not only analytical ...
user402444
2
votes
2
answers
175
views
Could concurrent user-triggered data fetches and inserts lead to deadlocks in a multi-user ASP.NET Core + MSSQL application?
I'm facing a tricky situation that might result from a not thoroughly thought-out design, and I'm hoping to understand whether a deadlock might be a realistic cause – and if so, how to prevent similar ...
2
votes
3
answers
322
views
Allowing POST as fallback for GET when query would exceed maximum length of URL
A typical search query looks something like
GET example.com/entity/search?q=John
If we want to add some filtering to this endpoint, we could for example add ...&filter= followed by a URL encoding ...
- 957
0
votes
3
answers
345
views
How does HTML-based HATEOAS apply in applications which also want to expose an external API?
I recently read through Hypermedia Systems, and found its arguments incredibly compelling. The book brought a lot of clarity and structure to ideas and frustrations that have been bouncing around in ...
- 111
1
vote
1
answer
259
views
System design for tracking viewed posts and returning unseen posts
I came across this system design question and have been wondering what is a good approach.
Requirement :
We have a typical blog or a mini social media kind of website where users create "Posts&...
- 154
3
votes
5
answers
1k
views
What is the root cause of a proliferation of "null checks"?
I work with a lot of Groovy code. One feature of the language is the "safe navigation operator" (?), which I think of as an inline null check. There are many things about Groovy that I like, ...
- 165
0
votes
1
answer
279
views
Should I let objects, whose copying is "costly", be naively copyable?
I'm devising an API - or actually, a wrapper API for another, lower-level API - in a programming language with objects.
This API represents some entity E which is reference-counted (for example - a ...
- 2,808
3
votes
3
answers
1k
views
Testing for non-existence of a method in API
I am designing a fluent builder pattern API that branches and allows different options based on what has already been called.
For example: Build().Foo().Bar() is valid code, but Build().Baz().Bar() ...
- 181
2
votes
3
answers
3k
views
How to design for API use cases that need different data from the same table?
I am building a web application. This application is meant to be a home for player rankings and tournament results for a competitive community. I have planned to do this in three layers: a database to ...
- 39
2
votes
1
answer
302
views
Designing a Role-Based Permission System for FastAPI: Integer Roles vs Database Roles?
Problem:
I am building a FastAPI based API and need to design a role-based permission system for authorization. Users can have one of three roles: Admin, Developer, and Operator. These roles are ...
- 131
1
vote
3
answers
170
views
How to put reference to external data in API input
This may be one example of a very general design question. Suppose I am building a service and I want the client to provide the location of some data on S3 which I will then read and process.
How do I ...
- 123
0
votes
1
answer
194
views
How to best handle keys for signing API callbacks
I am writing an API for a payment system. Third parties can register callback URLs that are linked to an account ID so that whenever a transaction involving that account ID is updated, my API calls ...
-1
votes
1
answer
86
views
Why would SMHI's weather API have this scaling for cloud coverage?
SMHI´s API have the below documentation for its properties. What intrigued me is the value range (0-8) for 'tcc_mean'.
Not only does it differ from other properties on the API, for example humidity ...
- 313
0
votes
1
answer
138
views
OpenAPI - `v0.x.x` as a way to denote unstability
In OpenAPI, is there a convention for denoting that your API is not stable yet?
In semantic versioning, the v0.x.x version number is usually used to indicate that the project is not stable yet. ...
- 123
0
votes
1
answer
549
views
Should you use nested routes within NestJS for a "RESTfull" API
Here is an Example API for managing companies, employees, and their children. My entity relationships are as follows:
company -1:n-> employees -1:n-> children
I’ve structured the API routes ...
- 111
4
votes
4
answers
958
views
Why is ArrayList not a Stack
I've been wondering for a while why an ArrayList does not have a stack-like interface (think push() and pop())
I frequently find myself using these constructs in Java:
list.get(list.size() - 1);
list....
- 151
0
votes
2
answers
301
views
Is caching external calls considered a state change in the context of safe HTTP methods
Starting Point:
According to https://www.rfc-editor.org/rfc/rfc9110.html#name-safe-methods, when making a GET call, the client is not requesting and not expecting the call to lead to any state changes....
- 17
-1
votes
2
answers
210
views
Rest Endpoint Design
I have 6 endpoints that return 6 json response:
/cities/{id} return a json object: {
"city": "Orlando",
"altitude": 10
}
/cities return an array: [{
"city": &...
- 531
1
vote
1
answer
210
views
Background thread processing vs queue based processing for relatively short tasks (max 30-40 seconds)
I need suggestion / recommendation on the design approaches mentioned below.
UseCase: I have a usecase where a client uses my system to generate some recommendations. Now, these recommendations are ...
- 19
0
votes
2
answers
168
views
Why did IHVs have never extended Direct3D through the facilities of COM on which it is based?
It is well known that Direct3D, unlike OpenGL, was never extensible in itself - a deliberate choice of Microsoft to favor the average user's expectations of predictable behavior and inherent ...
- 101
7
votes
4
answers
2k
views
How to maintain consistency when retrieving partial vs. full data in an API Resource
I'm working on a API for the logistics department, and I have a resource called logisticTransport, which is an entity in our database. I'm facing a challenge with maintaining consistency when ...
- 81
0
votes
1
answer
261
views
An adaptor layer for Pthread, C11, and C++11 threads compatibility
As my next spare-time project, I'm considering writing a suite of compatibility header and associated library, that eases the transition from Single Unix Specification v4 to v5 and C11/C17 to C2X. C++ ...
- 374
1
vote
1
answer
244
views
REST API with swappable backends
What would be the best way to have a single REST API but with multiple "backends" (Not sure if this is the correct terminology)? Currently we have a basket/cart API that handles product ...
- 137
6
votes
4
answers
2k
views
Separate unidirectional streams vs single bidirectional stream
Over the years I've run into (and created) APIs around device communication (Serial, USB, TCP, Bluetooth, etc). At the bottom of these APIs are usually byte streams that can send data to the device ...
- 171
0
votes
1
answer
231
views
How to handle data when source of truth is through API
I am making a webapp that deals with money movement. All the financial actions are done through an API. For example, right now I can create an account for a user, add funds to their account, transfer ...
- 109
1
vote
0
answers
120
views
How to model api error type with errorCode and parameters
I work on a spring kotlin backend which has an angular and a mobile frontend. We are currently working on error handling and we decided that the backend should return an error code, a general message (...
- 119
-1
votes
2
answers
627
views
Idempotency for a financial transaction API
Say you have a REST API endpoint like POST /move-money which transfers money from your main account to a savings pot. There are three path parameters
accountId for the user's account
potId for the ...
- 101
1
vote
1
answer
359
views
Is there a name for this API/type design principle? (I think of it as "state hygiene")
When designing types and their APIs, I try to adhere to these simple principles (which vaguely feel like one general principle to me) as much as feasible:
There is a one-to-one correspondence between ...
0
votes
1
answer
147
views
Designing a restful API for a desktop application to facilitate communication with other APIs
Just for some context, I am a CS student in my second-year who is working on a C++ desktop application (using the Qt framework) made by an engineering professor.
The application is an educational tool ...
- 1
-3
votes
1
answer
173
views
HATEOAS API - best practice to create multiple entities in one request
I have a HATEOAS API (in ASP.NET) with an endpoint:
POST /api/messages - to create a new message and it returns the location of a new message
Now I have a requirement that in some cases based on ...
- 97
11
votes
5
answers
3k
views
Why split up data retrieved from a database into multiple endpoints, if we need ALL the data anyway?
I have a "Games" API which retrieves video game data from a large database.
The /games endpoint returns some very basic information about the game, such as the title, description, etc.
More ...
- 121
0
votes
0
answers
292
views
Approach for comprehensive data/activity logging
I would like to be able to build up a log of user activities, capturing data such as who they were, where they logged in from, what activity did they take, and what data did they change (both before ...
- 275
0
votes
1
answer
723
views
POST and PATCH for a nested resource in REST API
One post can have many comments.
How can I design REST API urls for HTTP POST and HTTP PATCH for comments.
My idea is to have the following endpoints:
HTTP GET: /posts/{postId}/comments
HTTP GET (all ...
0
votes
3
answers
2k
views
Pagination api for huge number of records
I have an api which returns records given some constraint. Let's say 50000 records meet the constraint. Because we can not return all the records at once, so I have to implement pagination. I am also ...
- 144
1
vote
3
answers
684
views
Where should my users permissions live?
I'm building an application that allows the creation of users. These users can have profiles which define their permissions, as well as be given specific permissions.
Now I'm struggling on deciding ...
- 1,201
1
vote
5
answers
1k
views
DTO vs POJO (Entity) on POST request
If I have for example a User POJO like the following
@AllArgsConstructor
public class User {
@Id
private final String id;
private String username;
private String password;
private Date createdDate;...
- 111
1
vote
3
answers
361
views
Should this request return a status of 404 or a different status
We have an API that allows clients to POST some request which takes some time to complete, so the API simply places it on a message queue and returns a 202 (Accepted) and a new GUID in the body.
The ...
- 7,161
0
votes
1
answer
173
views
Function parameters using IDs vs full data objects
This is a design problem that has plagued me from web apps to embedded systems. It seems that my fellow developers don't really care at all, so I've never seen an established pattern.
In short: how ...
-1
votes
1
answer
77
views
Sending Notification pattern
I am new to backend development and I was building a feature for my project where I can send notifications to various channels (for example slack).
I have a written notification class, which loads the ...
- 99
2
votes
2
answers
625
views
Is service discovery an anti-pattern?
We deploy microservices in Kubernetes environment.
For providing a solution to a business use-case using microservices,
Is the idea of service registration and service discovery not an anti pattern? ...
- 769
1
vote
2
answers
90
views
Hierachy and API design for a CSS-selector-related Python library
I'm writing a Python CSS-selector library that allows one to write these kinds of expressions in Python as a pet project. The goal of the library is to represent selectors in a flat, intuitive and ...
- 137
3
votes
1
answer
186
views
Should I use transactions in this scenario?
I am writing a API endpoint in NodeJs, The code is roughly like this:
function myApi(myUserId, userIdToDelete){
if ( checkIfIAmAdmin(myUserId) ) {
deleteUser(userIdToDelete);
}
}
Now,...
- 69