Questions tagged [api-design]
Application Programming Interface (API) Design discusses best practises for creating libraries intended for general purpose or public use.
1,131
questions
-2
votes
3
answers
2k
views
What HTTP response to return for a patch request with partially correct and partially wrong
I have a campaign, which has URL as a child.
If I make a patch request to add a list of 3 URLs out of which first one is invalid URL, second URL already exists in the campaign and we do not want to ...
0
votes
2
answers
953
views
API Design. Should i use one update route or multiple for each business logic functionality
We are developping an app and I am not really pro at rest API etc.
We decided that a maximum of business logic should be in the backend and started to do "business" route. But sometime I ...
- 109
0
votes
1
answer
1k
views
Can I use POST request to read and transform data?
I'm developing an API that given a few parameters, reads the given data, transforms it and returns it as JSON.
Eg. (some logic included)
Request:
POST /myApi/exportAsText
Content-Type: application/...
3
votes
1
answer
1k
views
What are the best practices in public API vs internal only API being on the same service
I wanted to understand what are the best industry practices and the pros-cons in the following 2 choices:
A single service that serves internal only API and public API, vs
2 separate services - one ...
- 131
1
vote
4
answers
2k
views
Design REST Polymorphic API
I have a client/server application that exposes data and commands through REST APIs. This API exposes a GET /recipes/:id endpoint that instructs the client on how to show a recipe. A recipe can be ...
- 647
0
votes
1
answer
255
views
Is it a good idea to have conditional sync/async HTTP API
The api has one endpoint with some parameters. Based on these parameters I can predict how long the processing of the request would take. It can go from seconds(s) to tens of seconds.
When expected ...
- 103
0
votes
1
answer
277
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 ...
- 1,027
3
votes
2
answers
432
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 "...
- 139
1
vote
3
answers
570
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 - ...
- 113
2
votes
2
answers
2k
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 ...
- 123
1
vote
3
answers
332
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 ...
- 149
2
votes
3
answers
2k
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 ...
- 131
0
votes
1
answer
656
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 ...
- 121
0
votes
5
answers
1k
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 ...
- 383
1
vote
1
answer
6k
views
Is it considered as bad practice to have code on the __init__.py? [closed]
I am a bit confused about best practices when it comes to where and how to initiate the Flask() or FastAPI() for a data-intensive web API. The vast majority of the code available online is using this ...
- 155
55
votes
7
answers
11k
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:...
- 669
0
votes
2
answers
532
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", ...
-1
votes
2
answers
118
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 ...
0
votes
1
answer
92
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 ...
- 101
-1
votes
1
answer
117
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 -> ...
2
votes
2
answers
133
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 ...
- 151
7
votes
5
answers
3k
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:
...
- 261
1
vote
3
answers
650
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 ...
- 193
0
votes
1
answer
2k
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 ...
- 109
0
votes
2
answers
133
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 ...
- 967
0
votes
0
answers
59
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'...
- 1
0
votes
1
answer
517
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 ...
- 117
5
votes
3
answers
7k
views
REST API Design: Should the update (PUT) request include the ID in the resource 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://localhost:8080/library/book
...
- 1,615
0
votes
1
answer
99
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 ...
- 103
-1
votes
1
answer
607
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 ...
2
votes
1
answer
295
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 ...
- 91
-2
votes
1
answer
459
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 ...
0
votes
1
answer
306
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 = ...
- 321
0
votes
4
answers
123
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 ...
- 2,488
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, ...
-1
votes
1
answer
743
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 ...
- 125
-2
votes
1
answer
231
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 →...
- 7
1
vote
1
answer
372
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 ...
- 21
1
vote
2
answers
574
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 ...
- 201
0
votes
1
answer
295
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 ...
- 151
-1
votes
1
answer
389
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(...
- 334
1
vote
3
answers
148
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 ...
- 119
0
votes
1
answer
215
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 ...
- 11
0
votes
2
answers
228
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/...
- 103
2
votes
4
answers
1k
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., ...
- 157
0
votes
0
answers
48
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 ...
- 539
8
votes
6
answers
4k
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 ...
- 225
5
votes
1
answer
475
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 ...
- 159
-4
votes
2
answers
829
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
/...
-2
votes
1
answer
498
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
- ...
