Questions tagged [api-design]
Application Programming Interface (API) Design discusses best practises for creating libraries intended for general purpose or public use.
1,039
questions
0
votes
1
answer
26
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 ...
- 11.7k
0
votes
1
answer
179
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 = ...
CommunityBot
- 1
-1
votes
1
answer
84
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-...
- 11.6k
0
votes
2
answers
57
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 ...
- 61
3
votes
1
answer
189
views
API design reference , Empty list response (REST, SOAP, ...) type compatibility
Not sure where to go for an authoritive/text book answer for this question.
Suppose a service returns a list of something e.g. Customer, Employee, Fruits, etc.
What should be returned when the list ...
- 374
1
vote
1
answer
427
views
Correct to send JSON object in params?
Maybe I'm being dense, but is it common practice to create an API which requires users to submit GET params as an object? I've encountered one which has me submitting GET requests like...
http://www....
- 374
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 ...
- 11.7k
-2
votes
3
answers
74
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 ...
4
votes
3
answers
573
views
Designing a flexible search API response
Quick Summary
I'm building a search micro-service that will allow searching across different types of resources in a particular system (e.g. blog posts, users etc.). The API that will be exposed will ...
CommunityBot
- 1
3
votes
1
answer
134
views
What are some design ideas for a data mapping and transformation application?
Here is a high level outline of the project:
We frequently need to convert data from a new incoming system to our in house system (sort of a basic ETL process)
We would prefer to do this dynamically, ...
CommunityBot
- 1
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 ...
CommunityBot
- 1
0
votes
1
answer
72
views
Sending multiple calls from angular application
I am working in Angular project which is connected to REST API. Here we have an endpoint to create and update room types. POST endpoint for create and PUT endpoint for update exiting room types.
Both ...
CommunityBot
- 1
0
votes
2
answers
68
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 ...
- 30.1k
1
vote
1
answer
359
views
Securing API with JWT and elevated access using MFA
At my company we have a central auth server running IdentityServer. There are a number of applications providing some API to client applications. API requests are authenticated with JWT tokens issued ...
CommunityBot
- 1
0
votes
1
answer
70
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/...
- 123k
0
votes
1
answer
76
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 ...
- 13.1k
0
votes
4
answers
110
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 ...
- 4,799
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 ...
- 123k
0
votes
1
answer
645
views
Adding resources to subresource REST API
I'm trying to build an web API that closely represents a library of books. I currently have the following routes.
GET /api/books
GET /api/books/:bookID
GET /api/libraries
POST /api/libraries
This ...
CommunityBot
- 1
0
votes
1
answer
96
views
REST action as part of request body - action not stored alongside entity
I am working on an API that allows a client document to updated under the endpoint of PUT /client/{documentId}. As part of this document, I need to include an extra field 'ReplicateInManager' that ...
CommunityBot
- 1
-1
votes
1
answer
168
views
Recommended REST API design for transferring amount
I want to design a REST API given the following data model :
Accounts
UserId | Balance
user1 | 500
user2 | 200
And given the following Ui that must use the REST service for it's operation ...
- 374
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 ...
- 29.2k
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 "...
- 145k
1
vote
2
answers
211
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 ...
- 38k
1
vote
3
answers
124
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 - ...
- 186
4
votes
1
answer
248
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 ...
CommunityBot
- 1
1
vote
3
answers
135
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 ...
- 38k
0
votes
1
answer
115
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 ...
- 30.1k
0
votes
1
answer
417
views
Is it an anti-pattern on React to search for children with a specific element type?
Context
When designing the API of a React component, you may decide to receive props in a more semantical way. Here's a simple example
<Modal headerTitle="foo" />
vs
<Modal>
&...
CommunityBot
- 1
-1
votes
3
answers
162
views
Logging microservice - error level in URI or body?
For my use case I need to create a microservice that receives log messages through HTTP.
I'm wondering about the reasons to pick either of these:
Method: POST
URI: /{logLevel}/
Body: {
"message&...
- 154
1
vote
1
answer
288
views
Neo4j graph performance: should I cache slow queries in a separate database?
Setup/Intro
I have 10k+ nodes in my Neo4j graph in which I need to display a sub-graph (100-500 nodes) between 2 start/end nodes on the frontend app along with info about the critical path and all ...
CommunityBot
- 1
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 ...
- 363
1
vote
2
answers
229
views
Error Codes with Properties Files or Database
I'm about to implement Error codes for my company API, so, based on rfc7807 I will include a type which is an error type which is basically an error category, and inside those categories we have a ...
CommunityBot
- 1
-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 -> ...
CommunityBot
- 1
1
vote
1
answer
197
views
API / System Design [Flexible Authentication / Authorization]?
Background:
We're a smaller shop that puts out a number of products that require
authentication and authorization. We're currently using a 3rd party
service to "spin up new auth APIs" for ...
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 ...
CommunityBot
- 1
0
votes
1
answer
816
views
Is using web sockets between client-server to tranfer files the right approach? ( when multiple users connected on the same socket connection )
I am currently designing a system that lets users connect their Cloud Storage such as Google Drive, Dropbox etc and also to their physical filesystem (personal laptop/ ftp server etc.) and then can ...
CommunityBot
- 1
14
votes
4
answers
22k
views
Use composition and inheritance for DTOs
We have a ASP.NET Web API that provides a REST API for our Single Page Application. We use DTOs/POCOs to pass data through this API.
The problem is now, that these DTOs are getting bigger over time, ...
- 608
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:...
- 1,054
4
votes
1
answer
153
views
Dependency management for facades/adapters to cloud services (SemVer?)
Suppose I have a library, that basically works as a facade to some cloud service (e.g. JavaScript API that wraps around network calls to some RESTfull service). And once that service introduces a ...
CommunityBot
- 1
-1
votes
2
answers
61
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 ...
- 68.1k
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", ...
- 30.1k
0
votes
1
answer
80
views
Problems with software layers in complex query methods
I designed a rest api software with 2 simple layers: Controller and Service. The controller handles the coming http request and redirect to a service method. In the beginning of development every was ...
- 3,052
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 ...
- 12.1k
3
votes
5
answers
235
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:
...
- 22.1k
2
votes
2
answers
124
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 ...
- 145k
1
vote
3
answers
180
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 ...
- 22.1k
0
votes
1
answer
101
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 ...
- 159
0
votes
3
answers
599
views
Web API Bad Request design
My organization is developing a Web API server. We will also develop the only clients authorized to access the API. We will follow the usual technique of returning Bad Request (400) errors for data ...
CommunityBot
- 1
0
votes
3
answers
545
views
Calling Microservice using REST or dedicated client jar
When microservices need to talk with each other, the common practice will be to have some REST (or gRPC) communication.
I'm wondering what should be a better approach? (let's assume all services are ...
- 374