Stack Exchange Network

Stack Exchange network consists of 174 Q&A communities including Stack Overflow, the largest, most trusted online community for developers to learn, share their knowledge, and build their careers.

Visit Stack Exchange

Questions tagged [api-design]

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

0
votes
1answer
47 views

Use same API for both website and other clients or not?

Lets say I am building some large application ( multi-page app ) using Laravel. And laravel will allow me to make an API and a website on the same application. Since the website and the API ...
2
votes
3answers
156 views

Is something like “answers/{id}/downvote” considered RESTful?

Looking at Stack Exchange API docs, I see methods like answers/{id}/downvote answers/{id}/downvote/undo comments/{id}/delete. Should this be considered a RESTful API? (The docs does not mention the ...
-2
votes
1answer
63 views

Is it a good idea to ask for requestId in each API call?

I see some services which takes a requestId from client as the mandatory attribute while some services doesn't. I feel it is a good idea to have a request Id from the clients because it helps in ...
-2
votes
2answers
63 views

REST API acceptable design flexibility

I design and works on lot of projects involves REST APIs. But one question is always occur to me if it is acceptable way to do REST. So according to REST manuals online, REST is build upon two major ...
0
votes
0answers
41 views

How would design a wrapper for a large, multi-response api like the one described below?

Let me explain. Lets say there exist some service at some organization that exposes information on a company's assets, from employees company-issued devices(laptops and issues) to the the large xerox ...
0
votes
0answers
13 views

Separating models in a Backend-For-Frontend (BFF) API

At the moment I have a frontend client calling several backend REST APIs. For example a call may be to get information about a certain vehicle. Then the client will call REST API A to get some ...
0
votes
1answer
60 views

Avoid numerous dynamic_cast_ptr in the API design of polymorphic types

I am trying to design a geometric intersection API. Below is the code to represent geometric elements. #include <iostream> #include <memory> // Since I did not write the Shape class I ...
-2
votes
1answer
106 views

How to implement HTTP PUT correctly

I'm really looking for one good example how to PUT operations should be implemented correctly. What I understood until now: The operation must be idempotent When the resource doesn't exists it will ...
3
votes
2answers
126 views

Is this data as a result of business logic or is this content as a result of GUI logic?

I'm aware of the general distinction between data and content, namely context, but here I have a case that is clearly causing a lot of confusion and debate within the company I work for. There is a ...
5
votes
2answers
269 views

Why use multi-purpose getters that take an enum value, rather than separate getters?

I'm designing a C API which will have about a dozen getter functions for various values. Something like: bool getSomeBool(); bool getSomeOtherBool(); ... int getSomeNumber(); int getSomeOtherNumber();...
0
votes
0answers
24 views

Creating an API for adding third-party JIT support to a VM

I have created my own VM/runtime environment engine and I would like to give my runtime environment an API so that a developer could interface any type of JIT compiler to my VM. So far I've created ...
2
votes
5answers
249 views

Which layer should have responsibility for rounding numbers?

I am developing a financial system and want to have a defined policy for rounding monetary values. Given the following layers: View API Entity Model Persistence If I am passing a monetary value ...
0
votes
0answers
13 views

what's the proper way to interpret SREM results from REDIS

Background I am writing a REST API that exposes a method that allows the caller to delete a resource from the REDIS database. Because I'm using a SET, when you try to do an SREM, it will just return ...
1
vote
1answer
151 views

Why read and write API are good or why not?

While designing a complex system some of my colleges came back with the idea of having two separates APIs, one that will perform the writes into de databases and another one that will only do the ...
2
votes
1answer
132 views

C# .Net Core API design - interfaces vs DTOs

I'm designing a relatively simple web application using .net core. I've mostly done desktop development in my career so far, so I'm a bit new to the nuances between desktop and web development. In ...
50
votes
9answers
11k views

Should you guard against unexpected values from external APIs?

Lets say you are coding a function that takes input from an external API MyAPI. That external API MyAPI has a contract that states it will return a string or a number. Is it recommended to guard ...
2
votes
3answers
113 views

filesystem::path vs. optional<filesystem::path> as argument to function

Sometime ago in a code-review (C++) I suggested to change the input argument from Path type to Optional<Path>, where the function has specific logic for unset path. It looks for me intuitively ...
6
votes
7answers
527 views

Is an interface exposing async functions a leaky abstraction?

I'm reading the book Dependency Injection Principles, Practices, and Patterns and I read about the concept of leaky abstraction which is well described in the book. These days I'm refactoring a C# ...
2
votes
3answers
80 views

Permissive vs. Strict API Message validation

We had a interesting debate today over what our REST API should default to doing when validating a request body where unexpected fields are present. I think we ended the conversation in a good place, ...
-1
votes
1answer
69 views

Making the REST API to act as a playlist

Imagine the application I am building as a normal media playlist (Video / Music). On the client side, I select the files I want to play (Files are located on server), and I send its paths to the ...
1
vote
0answers
30 views

API as system controller

I'm developing a system, and I've had a question that might help other people. The system would be written in PHP, with a lot of chance of turning a mobile app later, too. Normally, I would create it ...
1
vote
0answers
19 views

Spring Boot and Mustache app separation of concerns

I am wondering how best to slice up a Java Mustache web app which has: Data layer (JPA, Repos, Entities, etc) Service layer getting data from other company web services outside the package Web/...
2
votes
2answers
71 views

Designing a Python API with defaults

I'm designing an API for a Python library. The user will create objects with several parameters. In most cases, the user will either leave these at their default values or will set them globally, for ...
1
vote
3answers
159 views

How can I resolve this **kwargs antipattern?

I am a hobbyist programmer, working on a much more complex Python project than I've attempted before, which is in the form of a Python library. I find that I'm often passing **kwargs around (as ...
6
votes
3answers
298 views

Should a high-performance API expose low-performance utility functions?

Context: I'm working on an open source project to solve a problem that comes up in ad-tech and social media data mining: indexing boolean expression trees, and matching them against incoming documents....
0
votes
2answers
87 views

Should we override all method overloads

Usually method overloads delegate their parameters to the more detailed overloads with default values. here is an example A(x) => A(x, null); A(x, y) => A(x, y, null); A(x, y, z) => ...; ...
2
votes
6answers
224 views

Difference between REST & HTTP REST implementations

REST principles are described here: https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_2 https://en.wikipedia.org/wiki/Representational_state_transfer#...
1
vote
1answer
65 views

Is GraphQL REST compliant (almost)?

I am writing an article about traditional REST vs GraphQL. However, after doing some research about REST (not just a specific implementation of REST), I started to see that GraphQL actually abides to ...
3
votes
1answer
101 views

params T[] vs IEnumerable<T> as parameter type

I know there's a proposal for params IEnumerable<T>. When designing an API, when should we choose params T[] (params array) over IEnumerable<T>. Or should both be implemented for better ...
3
votes
3answers
199 views

Should you retry 500 API errors?

My team and I are integrating with a 3rd party company and using their API to perform different CRUD operations. Their API isn't always reliable though. Maybe 0.1% of the time an API call just fails ...
-1
votes
1answer
55 views

Method that takes array parameter [duplicate]

I want to implement two methods: AddPlayers and AddPlayer. Is it better when AddPlayers calls AddPlayer or AddPlayer calls AddPlayers with a single item array? Is there a significant difference in ...
4
votes
3answers
147 views

Is checking if something exists responsibility of a caller or an API?

Is it better for an API when it provides additional methods that check if something exists before adding? For example: if (!userManager.HasPermission(user, "somePermission") userManager....
1
vote
1answer
49 views

Listing all sub-resources without parent scope

Let's say I have User resource which has Address sub-resource (let's forget about why this is a resource instead of attribute). To get a user's address, I can do GET /users/{id}/address Now I want to ...
1
vote
1answer
123 views

Java Class Design

I need to send a json response. I use the jackson library to convert the class to json. I have a core java class to which I need to add some more fields to create my json response. I came with two ...
5
votes
3answers
555 views

Is it okay to start a thread from within a constructor of a class

This is purely a design philosophy question in the context of C++. Is it a okay design philosophy to start a thread from within a constructor? I have a library whose sole responsibility is to ...
1
vote
2answers
78 views

API design - indicate that results were truncated

For reasons, my search endpoint returns a maximum of 50 results. I'm struggling with how best to tell the caller that their results were limited to 50. The best I've come up with is returning some ...
0
votes
0answers
36 views

How to properly structure a REST API for other sites to use that has user accounts?

I need to build a REST/HTTP API that has user accounts that other sites can use. It is my understanding that it is incorrect for the other sites(that use our API) to use a password field to allow ...
1
vote
1answer
59 views

Separation between regular web site requests and API requests

I have a doubt about the architecture of a web app when it comes down to differentiating between regular website requests and API requests. For the purpose of explaining, suppose I am the creator of ...
0
votes
3answers
71 views

Nesting Objects without Passing Arguments?

I have a couple of classes that I've nested together (not in the sense you may think so bare with me), to create what I call a prefab object (similar to Unity's prefab system). In this particular ...
0
votes
0answers
113 views

Does the fact that random.sample(seq, 1)[0] === random.choice(seq) mean that both functions should have the same precondition on seq?

I've read https://bugs.python.org/issue33098, which is about the following behavior of Python 3 a = {'1': 42, '2': 84} # keys are str on purpose, c.f. the issue import random random.choice(a.keys())...
1
vote
3answers
197 views

Does providing multiple APIs reduce code re-use

Within an organisation, suppose you have an internal tool used by different teams and for different use cases. This package offers APIs in different languages. One could say that having multiple APIs ...
0
votes
1answer
110 views

Where should a database API live?

Just read this article: https://microservices.io/patterns/data/database-per-service.html We are designing 2 microservices - both have tables in a shared db. What I'm wondering is if I build an API ...
0
votes
4answers
134 views

In API design, if I request a list of objects by ID, and one of those IDs is invalid/deleted, should the request fail?

Let's say I'm requesting a list of IDs for which I'd like to receive relevant DB entities (e.g., my-restaurant-api.com?restaurants=1,2,3). In this example, let's say ID 3 has been deleted and should ...
1
vote
3answers
388 views

Implementing Heartbeat using REST API

I have a server which is exposing API through REST. I need to implement a simple Heartbeat service to monitor this server status and availability of API. The interval of Heartbeat check will be every ...
0
votes
1answer
100 views

How to Redesign and scale legacy MVC application

I’m working with legacy web app for managing an animal shelter which need to be rearchitected/redesign, so it can scale and be possible to deploy in a central location. Currently it's physically ...
0
votes
1answer
93 views

Composition of microservices. Good or bad thing?

Hopefully this topic is not opinionated and I could maybe get meaningful answer please. Our problem is, imagine you have two microservices: Car and Driver. DTO of the driver could be let's say as ...
1
vote
2answers
125 views

How to decide if an API should be synchronous or asynchronous?

I am developing a service which will expose some APIs through REST end-point. I have some API which can take a lot of time like say 5 to 10 minutes to complete the requested operation. I am also ...
4
votes
5answers
406 views

Should we tailor APIs to the customer, or ask the customer to use the existing one?

I am a sole developer and I recently wrote a new web application in the form of a API with Swagger and front-end. This was customers could use the API on their own, usually forscripting. It is ...
0
votes
2answers
52 views

Should I put request context in path or in headers?

I'm designing a system that will Act as proxy calling a service on a back-end in context of user and his session Manage sessions for users on multiple back-ends I will expose the system over HTTP. ...
0
votes
2answers
62 views

Preferred method signature for API method involving DB interactions

I recently got into discussion about how the method signature should look like for an API method which doesn't expose internal objects used by application to caller. Here is how situation looks: Our ...