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
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 ...
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 = ...
-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-...
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 ...
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 ...
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....
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 ...
-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 ...
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, ...
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 ...
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 ...
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 ...
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 ...
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/...
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 ...
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 ...
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 ...
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 ...
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 ...
-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 ...
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 ...
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 "...
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 ...
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 - ...
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 ...
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 ...
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 ...
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> &...
-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&...
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 ...
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 ...
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 ...
-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 -> ...
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 ...
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 ...
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, ...
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:...
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 ...
-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 ...
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", ...
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 ...
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 ...
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: ...
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 ...
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 ...
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 ...
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 ...
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 ...

1
2 3 4 5
21