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
2answers
83 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) => ...; ...
-1
votes
0answers
46 views

Token-based registration

I'm trying to create a system where only users with a valid token can register. You may think of the token as a String which allows the user to register in my system. The token should cover: Status: ...
2
votes
6answers
206 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
53 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 ...
2
votes
1answer
74 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 ...
2
votes
3answers
162 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 ...
-2
votes
1answer
53 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 ...
3
votes
3answers
144 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
20 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
122 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
373 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
votes
0answers
120 views

Is it a code smell to expose a public method just for testing purposes? [duplicate]

Is it a code smell if the consumers of a class do not need a particular public method of the said class, but having the method simplifies its testing significantly? Consider the following example: ...
1
vote
2answers
77 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
32 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
44 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
63 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
79 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())...
0
votes
0answers
64 views

Updates and new functionalities in my App

I am currently working on an android app and want to implement more functions in the future for this app. Most devices are set for an automatic update cycle and keeps getting the newest version of an ...
1
vote
3answers
161 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
109 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
131 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
196 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
86 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
84 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
103 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
384 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
50 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
60 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 ...
2
votes
4answers
142 views

User calling REST APIs on behalf of a different user

Here's an example: GET /posts POST /posts GET /posts/{post_id} PUT /posts/{post_id} This api is being used by SUPER_ADMIN as well as CONTENT_WRITERS. Its working great. If user is logged in as a ...
-2
votes
1answer
65 views

Python API Design for workload automation software

I want to expose APIs in python for my workload automation software. I have a Job class as defined/outlined below. Instance of this job class represents a particular Job run. Job can have multiple ...
7
votes
5answers
332 views

Information Hiding v.s. Static Type Safety

I'm working on a project with others and we have a discussion about information hiding and static type safety. Our scenario is described below. Language: C++11 Scenario: We want to create a tree-...
1
vote
2answers
151 views

Is passing an ErrorMessage to be populated inside the receiving method an anti-pattern?

I come from a Java background, and my colleague is from .NET. We are working on a Java project and I saw him create a method like this: public Object myMethod(Object[] param1, ErrorMessage ...
-1
votes
1answer
29 views

Measuring the usability / ease of use of RESTful API in Mobile Cloud Computing?

APIs vary in their complexity, functionality and also usability. In Mobile Cloud Computing (MCC) applications, which are mainly mobile applications that offloads processing / storage to the cloud, ...
1
vote
2answers
145 views

Is it RESTFul for an endpoint without a path parameter to always have a single resource as a result?

While creating tools for an api, I've noticed the following inside the api specification: GET /cookie-orders returns the following structure as a 200 result: { "first":true "last":false ...
0
votes
1answer
56 views

Is there an equivalent to HTTP status codes for WebSockets messages?

I'm developing a WebSocket API and I was wondering if there was either a standard or best practice for responding to client messages. For example, if my API is expecting only stringified numbers but ...
2
votes
1answer
56 views

What to choose, ioctl-like interface or a set of distinct methods?

I am implementing a messaging protocol between nodes on a network and i am wondering how to expose the messaging system interface to the programmers. The messaging protocol supports a set of commands ...
0
votes
2answers
97 views

Check or not objects in a Javascript API?

I'm writing an API in JavaScript, and I'm confused whether or not I should check if the API user is passing me the correct type on which the API expects to work. Actually not the type, but if you are ...
0
votes
1answer
47 views

Fastest way to return a list of records depending on many many-to-many relationships

I'm developing an API in Rails and the following requirement is established (it's really more complicated, but I want put a simple example): There are users and messages. users have a gender (...
0
votes
1answer
101 views

What HTTP action and return value should be used on resource's action

I have a question about how I should implement a new action for a resource on my API layer. I have a Timesheet which is used by people to let us know how many hours they worked on a job. This ...
1
vote
1answer
57 views

Repository pattern, call another API that updates a SOR's from service or repository class?

We are working on API's that call other API's that will inevitably retrieves/update a system of record like an SQL, MySQL or other database. Sometimes we'll have 3/4 layers of API's before the SOR is ...
2
votes
0answers
75 views

Is “equivalent” functions / methods readability worth its maintanability cost?

First of all, I am sorry if it is a duplicate, I could not think of any "correct" wording to search about this. Second let me clarify: By "equivalent" I mean methods that are meant to have the same ...
2
votes
5answers
364 views

In a REST API, should you correct user input on server side?

We have a REST API with an endpoint accepting JSON data from the client. One of the JSON fields is a URL that will be rendrered to other users as a hyperlink to a website page associated to the ...
0
votes
2answers
122 views

How to handle state of an object? And how to enrich the state transition logic?

I am designing a class that has a state. I wonder if I should expose that state in the interface in view of allowing a decorator to enrich the state transition logic. Shall my design expose ...
-2
votes
1answer
42 views

Should API also authenticate users from front end app?

I am building an API using Laravel and am looking at using Laravel/Passport for authentication - but I am struggling with a design decision. The API will be consumed by multiple other applications / ...
6
votes
3answers
412 views

What reasons are there AGAINST using only POST HTTP verb in an API?

I am researching before starting to work on an API for a web-service I am building. The goal is to be very quick and easy to adapt and use for other developers but fairly hidden for clients using a ...
1
vote
2answers
93 views

C++ - Is it a good idea to make separate headers as API?

Let's say I have a library code main.cpp, where are 3 classes implemented: Inner1, Inner2 and Outer. Inner1 and Inner2 are only being used in main.cpp and they're not going to be used anywhere else. ...
0
votes
1answer
87 views

Dealing with child collections updates in Web API

Let's take some classic enterprise example: Order and OrderItem public class Order { public Guid Id { get; set; } public ICollection<OrderItem> Items { get; set; } } public class ...
0
votes
0answers
42 views

What goes in the meta attribute in an API

I am using the JSON:API standard to write my API: http://jsonapi.org/ An example is as follows: { "data": { "type": "offer", "id": "1", "attributes": { "title": "50% off!", ...
0
votes
2answers
142 views

Support multiple request formats for single REST endpoint

I'm building an REST API that exposes a callback method for a 3rd-party service. Let's imagine that there are two similar (but not identical) 3rd-party services. They both call back my API (POST /...
1
vote
1answer
41 views

Board support driver for custom board - API design - MCU resource configuration

I have got to implement a board support package for a custom board, and I would like to know your opinion about the different approaches of designing board support drivers. My custom board pupulates ...