Questions tagged [api-design]

Application Programming Interface (API) Design discusses best practises for creating libraries intended for general purpose or public use.

Filter by
Sorted by
Tagged with
-1 votes
0 answers
23 views

Licensing scenario question

Problem: I have an API that lives in my organizations tenant. We use scopes and roles through Azure AD to authorize our API endpoints. These scopes and roles are assigned in our clients app ...
user avatar
-3 votes
0 answers
26 views

Structuring a database for an investment portfolio?

would really appreciate some general advice on the structure of an app i'm building. I'm essentially trying to re-create an investment portfolio app using a MERN stack. Something very similar to ...
user avatar
0 votes
1 answer
57 views

How do I make a breaking change to a Nuget package?

My apologies if some details here are deliberately vague, I don't want to get side-tracked by the specifics of the language, frameworks, third-party API, etc. Some months ago, I developed some code to ...
user avatar
2 votes
2 answers
127 views

What is the alternative to checked exceptions in API/interface design?

Despite checked exceptions being generally bad practice and anti-pattern, I find one feature very useful: having list of checked exceptions part of function signature. Checked exceptions are "...
user avatar
  • 129
1 vote
3 answers
109 views

REST API endpoint to request all available data from a resource

I am developing a REST API where users can request data from one or more sensors, using the following scheme: GET /sensors - returns a list of available sensors GET /sensors/<sensor_ids>/data - ...
user avatar
  • 113
1 vote
2 answers
179 views

Should you limit the size of JSON array to avoid abuse? Or is this already covered by size limits?

I'm working with a basic REST API, through user interaction on the UI, the JSON object is built up, including Arrays and a POST is sent to an endpoint using this object as the request body. For ...
user avatar
  • 113
0 votes
1 answer
81 views

How to handle API's validation based on a flag

I have the following case: If the user is in the UK, the server needs to validate the bank details as Account number and Sort code number If the user is in France, the server needs to validate the ...
user avatar
1 vote
3 answers
119 views

In RESTful APIs, what's the proper way to have different resource properties based on user authorization?

I'm struggling with defining proper endpoints for a RESTful API, given the following requirements: We have an existing /customers endpoint, which when called with the GET verb, returns a list of ...
user avatar
  • 119
0 votes
1 answer
86 views

Plugin architecture vs Interface Segragation Principle (SOLID) [closed]

Uncle Bob's Interface Segragation Principle (ISP) tells us that many client-specific interfaces are better than one general-purpose interface. But plugin architecture in common case suppose to have ...
user avatar
  • 113
0 votes
1 answer
101 views

REST API Design: Should we have separate endpoints for same resource if the system uses both ElasticSearch and MySQL?

Suppose we have a resource which uses either MySQL or ElasticSearch, depending on whether the query params require full-text search or not. For example the possible query filters are: fk_id which is a ...
user avatar
0 votes
5 answers
128 views

Standard Error response for Backend API failure

In REST APIs, http error codes 4XX, 5XX are used to convey error messages on the server. When the API itself is dependent on another backend API, is it a good practice to expose error codes or error ...
user avatar
  • 353
51 votes
7 answers
8k views

Why do so many standards for JSON API response formats contain a "success" property in the response body instead of just using HTTP status codes?

I was researching about best practices for standardised JSON response formats for APIs, according to various sources available online general consensus looks something like this: //Successful request:...
user avatar
  • 629
0 votes
2 answers
68 views

REST Api - deleting a resource based on either ID, or its OwnerID

I have this list of Notes: public static List<Note> _notes = new List<Note> { new Note { Id = new Guid("00000000-0000-0000-0000-000000000001"), CategoryId = "1", ...
user avatar
-1 votes
2 answers
56 views

Best practices for API design for an E-Commerce System

I have a few basic questions on how to implement an API for a basic e-commerce system. The relevant entities are Customer, Puffle, and Review. Each Puffle can have zero or more Reviews. Each Review is ...
user avatar
0 votes
1 answer
66 views

Best way to calculate profit/loss with historical data

Problem I need to build a profit/loss graph for a mobile app. The api from which I can get the historical price data only allows me to retrieve 1 item at a time. If the user has 500 items that would ...
user avatar
  • 101
-1 votes
1 answer
69 views

Design: Designing a Status Tracking Tool

We have a robust set of micro-services available. For simplicity, let us call the services S1 S2 S3 S4 S5 For simplicity, think of the flow to be this. S1 -> performs step1 (start step) S2 -> ...
user avatar
2 votes
2 answers
122 views

Use of internal interface around paid APIs

Note: I'm new to using paid APIs (like Stripe, GPT-3, Twilio, ...). When you are using a paid 3rd-party API, you are essentially betting on them keeping reasonable prices in the future, right? So in ...
user avatar
3 votes
5 answers
199 views

Version REST APi as a whole, or by endpoint

I had a discussion with a colleague of mine today regarding versioning of a REST Api. We currently have an API with support for versinong by providing the correct version in the URL. So for instance: ...
user avatar
  • 193
1 vote
3 answers
167 views

Benefits of internal API over direct implementation in UI

What we often see is that software companies create an internal API which is then consumed by their own user interface. And we were trying to find the benefits of those, other than it's easy/easier to ...
user avatar
  • 183
0 votes
1 answer
93 views

Designing a system to hit multiple HTTP requests serially

Hope this is the right StackExchange community to ask this question. I am building a (Python) project that will have a list if URLs to hit. They have to be hit serially, and part of response of one ...
user avatar
  • 109
0 votes
0 answers
25 views

How to keep in sync definitions of exchange data

I am a single, amateur developer and I am currently learning on a server (Golang) and client (TypeScript, Vue) application. The client calls the server through a REST-like interface and exchanges a ...
user avatar
  • 1,555
0 votes
2 answers
77 views

Is it bad style to share a Model class between two API Endpoints?

I have the following scenario: My .NET Core API has two Endpoints CreateProduct and UpdateProduct. The only difference between the two will be that UpdateProduct will need to know the ID of the ...
user avatar
  • 495
0 votes
0 answers
44 views

Best way to align multiple RESTful API's through an API gateway

We currently have a monolith public api which serves most of our api endpoints. This has introduced a bottleneck as the owning team needs to make changes to publicise anything new and other teams don'...
user avatar
  • 1
0 votes
1 answer
87 views

Passing set of flags from browser to backend by message header or body?

I am exploring two ways of passing certain flags representing user behaviour to the backend. When should I pass flags via headers and update routing based on header, and when is it more appropriate to ...
user avatar
1 vote
3 answers
240 views

REST API Design: Should the update (PUT) request include the ID in the resouece URL

When designing a REST API for update request. Usually PUT is used. Question: should the resource URL include the id usually? For instance, there is a book resource: http://localshot:8080/library/book ...
user avatar
  • 1,467
0 votes
1 answer
51 views

Decoupling data validation from data processing

I'm trying to implement a web service API client using the guidlines i've found in this article: https://www.oreilly.com/library/view/designing-evolvable-web/9781449337919/ch09.html As it comes to my ...
user avatar
  • 103
0 votes
0 answers
35 views

HTTP and gRPC status codes equivalent to Nginx's 499 code (client closed request)?

Nginx introduces a 499 code, which is used when the client closes the connection before the server could respond. This is specific to Nginx. What would be the equivalent plain HTTP and gRPC status ...
user avatar
-1 votes
1 answer
104 views

Two layers of DTO's for API's with Entity Framework

I am building an API which, amongst other things, needs to handle users. I am building it with C# 10 and .NET 6. In order to receive/return data in the API end points, I am using records. So for ...
user avatar
2 votes
1 answer
121 views

Wrapping a legacy C++ codebase with a C API

I have inherited a large C++ codebase implementing various Windows desktop applications, services and libraries using Windows MFC. There are no automated tests. We need to decouple the UI and retain a ...
user avatar
  • 91
-2 votes
1 answer
93 views

Should I use http status code 402 in my api specification for api methods that allow payment?

According to the MDN the http protocol has the 402 status code: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses And is used for methods that require payment. Also RFC ...
user avatar
0 votes
1 answer
172 views

Should i specify that my methods "throws ConstraintViolationException" if the exception is actually thrown by a CDI interceptor?

Here is a sample method: @ApplicationScoped public class MyClass{ public void getUser(@Min(1) int id){ //get User logic } } I'm in a CDI environment with @ValidateOnExecution(type = ...
user avatar
  • 299
0 votes
4 answers
108 views

API design: Should a count() of a set of consecutively-id'ed elements return a size type?

I'm writing C++ code, where the standard library has an idiomatic type for representing sizes: std::size_t. Now, I'm writing a function which counts certain kinds of objects; and these objects have ...
user avatar
  • 2,365
0 votes
1 answer
54 views

Correct selection of flags for extension

In my library (DLL), I have extensions for List like the next one. <Runtime.CompilerServices.Extension> Public Sub Store(Of TVal As IFullyOperable)(items As List(Of TVal), w As BinaryWriter, ...
user avatar
-1 votes
1 answer
116 views

rest api design for bulk post [closed]

Is it OK for an API to accept either an object or an array on the same endpoint? I want to allow the user to post multiple items at once. I am thinking of creating a different endpoint, but then it ...
user avatar
  • 125
-2 votes
1 answer
93 views

How often should I request a token when communicating with a third-party API?

I have an ASP.net web API. I would like to call another API that has an authentication token inside my API. The code flow is as follows: My API is called → Get authentication token from 3rd party API →...
user avatar
1 vote
1 answer
280 views

MVC-like architecture: Model-Controller communication of results/status

I'm struggling on designing a solid architecture for my project. In particular, I don't know how to handle the communication between the models and the controllers. My goals are: Following the ...
user avatar
0 votes
2 answers
194 views

Should a client / server share error codes?

I am in two minds about sharing client / server errors codes. We are writing both ends of the system, if our API was external this would not be possible, but that requirement is very unlikely. So an ...
user avatar
  • 151
0 votes
0 answers
16 views

How should I design a web application that will show outputs and issue commands on devices using MQTT?

I'll be developing web application (most probably an Express.js REST API) that will include user management, device management by users. There will be users which will sign in and log in to the system....
user avatar
0 votes
1 answer
66 views

How to Properly Design an API Prefetch System

I'm creating an API for a web service. There are a couple of endpoints in this API that require some time (lets say +5min) to compute, so I'm creating a prefetch system that will call in the ...
user avatar
  • 131
-1 votes
1 answer
128 views

Why is `replace(dataclass, **kwargs)` a function, and not a member?

Imagine a simple data class: @dataclass class Settings: m: int s: str old = Settings(m=10, s="ten") It feels normal to write new = old.replace(m=1), but we have to write new = replace(...
user avatar
  • 334
0 votes
0 answers
27 views

REST API partially incorrect request handling

I'd like some insight/heuristics on how to tackle a specific kind of situation. Entity A, B have a parent child relationship with Entity C. Entity A creation is done thru a POST /createA API in ...
user avatar
0 votes
1 answer
157 views

Wrapping the UI framework

I want to write an application where I would delegate certain functionalities to 3rd party libraries. To make sure the code remains modular, I want to put these libraries behind an interface so I can ...
user avatar
0 votes
2 answers
77 views

How to structure URL when retrieving a REST resource by an attribute that isn't the ID?

Let's say I have a collection of cars, all identified by VIN, such that cars/xyz123 will return the car with that VIN. Furthermore, I can get subsystems (children) by using URIs similar to cars/xyz123/...
user avatar
  • 103
2 votes
4 answers
316 views

Should a REST API always document its response content?

I am using a REST API that is being developed at my workplace. The documentation clearly states the HTTP request type (POST), the URL endpoint, and the "payload" in curly brackets, i.e., ...
user avatar
0 votes
0 answers
28 views

How to validate against changes to "illegal paths" in backend requests for complex data structures?

We are building a backoffice web application where people are making changes to an array of nested objects. Because of totally non relevant business reasons there are things that users cannot change ...
user avatar
  • 519
8 votes
6 answers
739 views

How should an API handle unsupported fields?

Let's assume I have this API on /api/v2/persons that enables me to create new entries by POSTing this JSON: { "name": "me" } The API is implemented using Spring Boot and if ...
user avatar
  • 225
4 votes
1 answer
244 views

Can an api gateway handle websockets requests besides regular http requests at the same time?

I am working on social platform with a distributed architecture. The platform should offer a chat module, but since the most efficient way to implement a chat is using websockets. I am not sure what ...
user avatar
  • 149
-4 votes
2 answers
269 views

One rest api endpoint for multiple resources [closed]

Hello im about to create dasbord for my website.. Dashboard will have multiple subpages like users, posts, roles etc.. I was thinking i would use only one rest api endpoint for those resources like /...
user avatar
  • 111
-2 votes
1 answer
97 views

rest api - can two endpoints return different models if both return order?

Is it under the rules of REST to return a different model of 'order' if someone call: /me/orders/222 Return values: - OrderId - Price or /customers/111/orders/222 Return values: - OrderId - Price - ...
user avatar
0 votes
1 answer
231 views

Best way to enable field removal through PATCH

I am developing a REST API and I would like to allow the users to remove a field of the object through PATCH. My idea was to use a null field on the PATCH body as a signal to remove this field of the ...
user avatar
  • 19

1
2 3 4 5
21