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
2 answers
58 views

Designing class for fixed-size data structure backed by ArrayList

Say we want to write a Java class that represents a fixed-size list. Let's call it Chunk.java (as in, it represents a chunk of data to be processed or sent somewhere). My implementation of this class ...
user avatar
-1 votes
2 answers
198 views

Is it bad practice to have too many direct subclasses?

Let's say we have an undo/redo system and we have a superclass storing an object that should later form a tree of the attributes that can be undone/redone. This would require every class that should ...
user avatar
  • 19
0 votes
1 answer
34 views

Handling resource not found

I have an endpoint GET home/{homeId}/laptops . Its response is : {"homeId":string,"laptops":string[]} If homeID does not exist I can return '404 Not found' OR an empty response ...
user avatar
-1 votes
1 answer
96 views

Designing APIs that don't expose database primary keys

People say "don't expose primary keys from the database in your API" because its a major security leak, so I'm trying to come up with a way for: RESTful HTTP requests to reference server-...
user avatar
0 votes
2 answers
64 views

Having a front end grid component fetches its metadata from the backend, is this a "bad" strong coupling?

The idea is that for each resource we want to dispaly in a grid, there will be one endpoint for data and another for metadata. The metadata endpoint will bascially return a list of columns and their ...
user avatar
-2 votes
3 answers
76 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 ...
user avatar
0 votes
2 answers
69 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 ...
user avatar
  • 109
0 votes
1 answer
71 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/...
user avatar
0 votes
1 answer
77 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 ...
user avatar
  • 101
0 votes
4 answers
113 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 ...
user avatar
0 votes
1 answer
101 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 ...
user avatar
  • 103
0 votes
1 answer
62 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
151 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
127 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
215 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
105 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
137 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
  • 121
0 votes
1 answer
116 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
137 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
  • 363
52 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
  • 639
0 votes
2 answers
69 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
64 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
70 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
71 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
125 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
240 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
181 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
146 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
26 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,541
0 votes
2 answers
78 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
  • 505
0 votes
0 answers
46 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
102 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
457 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,487
0 votes
1 answer
52 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
45 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
133 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
129 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
99 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
181 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,400
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
152 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
99 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
1 vote
2 answers
209 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
  • 161
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
70 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
132 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
2 answers
88 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
159 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

1
2 3 4 5
21