Skip to main content

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
341 votes
14 answers

Should you write your back-end as an API?

I had a heated discussion today about our MVC application. We have a website written in MVC (ASP.NET), and it usually follows the pattern of do something in the view -> hit the controller -> ...
NibblyPig's user avatar
  • 3,015
205 votes
4 answers

What is an Anti-Corruption layer, and how is it used?

I'm trying to figure out what the Anti-Corruption layer really means. I know that it's a way to transition/work around legacy code or bad APIs. What I don't understand is how it works and what makes ...
knownasilya's user avatar
  • 3,214
203 votes
7 answers

How do searches fit into a RESTful interface?

When designing a RESTful interface, the semantics of the request types are deemed vital to the design. GET - List collection or retrieve element PUT - Replace collection or element POST - Create ...
Rob Baillie's user avatar
  • 2,446
132 votes
14 answers

Should the solution be as generic as possible or as specific as possible?

Say I have a entity that has "type" attribute. There could be 20+ possible types. Now I'm asked to implement something that would allow changing the type from A->B, which is the only use case. So ...
LoveProgramming's user avatar
115 votes
5 answers

Should I return an HTTP 400 (Bad Request) status if a parameter is syntactically correct, but violates a business rule?

Say that I have a REST endpoint that takes an integer as a parameter: /makeWaffles?numberOfWaffles=3 In this case, I want the number to be positive because I can't make a negative number of waffles (...
Thunderforge's user avatar
  • 2,718
98 votes
8 answers

RESTFul: state changing actions

I am planning to build a RESTfull API but there are some architectural questions that are creating some problems in my head. Adding backend business logic to clients is an option that I would like to ...
Miro Svrtan's user avatar
  • 1,139
76 votes
6 answers

Many small requests vs. few large requests (API Design)

I'm currently working on a project with an organization as follows: Client - Gets data from the main server via REST api. Server - Requests data from various other servers via third-party APIs Third-...
williamg's user avatar
  • 861
72 votes
4 answers

Why PATCH method is not idempotent?

I was wondering about this. Suppose I have a user resource with id and name fields. If I want to update a field I could just do a PATCH request to the resource like this PATCH /users/42 {"name&...
seldon's user avatar
  • 972
64 votes
1 answer

null vs missing key in REST API Response [closed]

Say in my application, some users give us their last name, and others do not. In a REST API response, which body is preferred: With a "null" value: {"firstName": "Bob", "lastName": null} Or just a ...
jtmarmon's user avatar
  • 978
62 votes
14 answers

RESTful API design. What should I return if there are no rows?

I'm currently coding an API for a social network with the Slim Framework. My question is: What are the best practices when there are no rows to return in the json structure? Lets say that this call /...
Andres SK's user avatar
  • 723
58 votes
3 answers

Should Microservices talk to each other?

I'm designing an application using Micro-Services and I'm unsure on the best mechanism to use to collect data from multiple services. I believe there are two options: Integrate an 'inter-service' ...
KidCode's user avatar
  • 2,183
56 votes
7 answers

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:...
Šime's user avatar
  • 679
54 votes
2 answers

REST API - Should API Return Nested JSON Objects?

When it comes to JSON APIs is it good practice to flatten out responses and avoid nested JSON objects? As an example lets say we have an API similar to IMDb but for video games. There are a couple ...
greyfox's user avatar
  • 869
53 votes
9 answers

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 ...
Adam Thompson's user avatar
52 votes
10 answers

What should be the http status code for "Service not available in your area" error?

Our service is in 5 cities right now. If someone tries to call our service API from any other city, we want to throw this error Service not available in your area. The question is, what is the ...
Shaharyar's user avatar
  • 865
50 votes
2 answers

REST API Design: Multiple calls vs. single call to the API

We are developing a Rest API for eCommerce website which will be consumed by mobile apps. In the home page of an app we need to call multiple resources like Sliders, Top Brands, Best Selling Products,...
Shaiju T's user avatar
  • 611
49 votes
11 answers

Should a REST API return a 500 Internal Server Error to indicate that a query references an object that does not exist?

I am working with a REST API which resides on a server that handles data for a multitude of IoT devices. My task is to query the server using the API to collect specific performance information about ...
JYelton's user avatar
  • 734
49 votes
4 answers

What's so bad about the DOM?

I keep hearing people (Crockford in particular) saying the DOM is a terrible API, but not really justifying this statement. Apart from cross-browser inconsistencies, what are some reasons why the DOM ...
wheresrhys's user avatar
46 votes
6 answers

How necessary is it to follow defensive programming practices for code that will never be made publicly available?

I'm writing a Java implementation of a card game, so I created a special type of Collection I'm calling a Zone. All modification methods of Java's Collection are unsupported, but there's a method in ...
codebreaker's user avatar
  • 1,724
46 votes
5 answers

How does a REST API fit for a command/action based domain?

In this article the author claims that Sometimes, it is required to expose an operation in the API that inherently is non RESTful. and that If an API has too many actions, then that’s an ...
leifbattermann's user avatar
44 votes
8 answers

Why does java.util.ArrayList allow to add null?

I wonder why java.util.ArrayList allows to add null. Is there any case where I would want to add null to an ArrayList? I am asking this question because in a project we had a bug where some code was ...
Alfredo Osorio's user avatar
44 votes
3 answers

Recommended HTTP status code for "plan limit exceeded" response

I'm designing a REST API for a project where users are always on one of several "plans" - each plan defines some resource limits, such as the max number of users an account may have or the max number ...
shevron's user avatar
  • 591
43 votes
6 answers

Should an HTTP API always return a body?

Is there some sort of standard regarding HTTP API responses? After reading this discourse thread I started to wonder. We are developing our public HTTP JSON API at my work, and we do not return ...
juan's user avatar
  • 1,749
42 votes
1 answer

How to design a REST API that can "prompt" the client about long-running operations?

Say you were to develop a REST API that provides access to a set of complex, long-running, operations. The typical paradigm for an API like this (as I understand it) usually involves (the client) ...
meci's user avatar
  • 531
38 votes
6 answers

Is there a pattern for handling conflicting function parameters?

We have an API function that breaks down a total amount into monthly amounts based on given start and end dates. // JavaScript function convertToMonths(timePeriod) { // ... returns the given time ...
CalMlynarczyk's user avatar
38 votes
5 answers

How to describe an architectural shift that intentionally breaks REST standards?

I'm proposing changes to a very poorly architected software project that suffers from a multitude of problems. At a high level the project utilizes Angular on the front-end and consumes various REST ...
Ben Harrison's user avatar
  • 1,233
37 votes
7 answers

How do I convince my boss to use REST over SOAP? [duplicate]

We need to create an API to our system. How do I convince my boss that REST is a better option than SOAP (or XML-RPC)? I say REST is... easier to implement and maintain not much new to learn -- ...
treecoder's user avatar
  • 9,495
34 votes
3 answers

Is it OK to return HTML from a JSON API?

On my current project I am responsible for the implementation of a service which involves the consumption of newly created RESTful APIs, documented as solely supporting JSON. The client consistently ...
phillip.darley's user avatar
33 votes
3 answers

What is the best pattern for adding an existing item to a collection in REST API?

I'm designing a pragmatic REST API and I'm a little stuck on how best to add existing entities to a collection. My domain model includes a Project that has a collection of Sites. This is a strict many-...
Jamie Ide's user avatar
  • 433
32 votes
10 answers

Why is Math.Sqrt() a static function?

In a discussion about static and instance methods, I always think, that Sqrt() should be a instance method of number types instead of a static method. Why is that? It obviously works on a value. // ...
Residuum's user avatar
  • 3,322
32 votes
5 answers

Function returning true/false vs. void when succeeding and throwing an exception when failing

I'm building an API, a function that uploads a file. This function will return nothing/void if the file was uploaded correctly and throws an exception when there was some problem. Why an exception ...
Accollativo's user avatar
32 votes
3 answers

Is there a list of common usernames to reserve in a new system?

I need to reserve usernames in my new website. These generally fall into three categories 1) usernames no-one should have (eg: admin, user, service, help, root, etc) 2) names of super famous people ...
user avatar
32 votes
4 answers

Microservices and data storage

I'm considering moving a monolithic REST API to a microservice architecture, and I'm getting a bit confused about data storage. As I see it, some of the benefits of microservices would be: ...
penalosa's user avatar
  • 429
30 votes
3 answers

When should I use string_view in an interface?

I'm using an internal library that was designed to mimic a proposed C++ library, and sometime in the past few years I see its interface changed from using std::string to string_view. So I dutifully ...
T.E.D.'s user avatar
  • 1,069
29 votes
3 answers

Is it Good Practice to Only Expose Interfaces

I''m working on a C# library where the API provides several public interfaces and a single concrete factory class (itself an interface implementation). This factory provides implementations of the ...
Bondolin's user avatar
  • 403
29 votes
5 answers

How best do you represent a bi-directional sync in a REST api?

Assuming a system where there's a Web Application with a resource, and a reference to a remote application with another similar resource, how do you represent a bi-directional sync action which ...
Edward M Smith's user avatar
28 votes
6 answers

Why use an opaque "handle" that requires casting in a public API rather than a typesafe struct pointer?

I'm evaluating a library whose public API currently looks like this: libengine.h /* Handle, used for all APIs */ typedef size_t enh; /* Create new engine instance; result returned in handle */ int ...
Jonathon Reinhart's user avatar
27 votes
2 answers

Should I make up my own HTTP status codes? (a la Twitter 420: Enhance Your Calm)

I'm currently implementing an HTTP API, my first ever. I've been spending a lot of time looking at the Wikipedia page for HTTP status codes, because I'm determined to implement the right codes for ...
Max Bucknell's user avatar
26 votes
3 answers

RESTful API: HTTP verbs with shared or specific URLs?

While creating a RESTful API, should I use HTTP Verbs on the same URL (when it's possible) or should I create an specific URL per action? For example: GET /items # Read all items GET /...
53777A's user avatar
  • 1,718
26 votes
10 answers

API design: concrete vs. abstract approach - best practices?

When discussing APIs between systems (on the business level) there are often two different point of views in our team: some people prefer a more - lets say - generic abstract approach, other a ...
erik's user avatar
  • 377
25 votes
4 answers

When creating an api should I stick with small functions and many calls, or a few calls and large functions?

I have a rails platform that I maintain. It has a lot of different web applications built on top of it. However now a client is asking for an API so that they can keep users on their site, but take ...
Ryan's user avatar
  • 550
24 votes
11 answers

"Public APIs are forever: Only one chance to get it right"?

In an OS book I just read that, "Public APIs are forever: Only one chance to get it right". Is it true? Is it applicable only in APIs of Operating Systems or other APIs too? For example, will this be ...
user avatar
22 votes
9 answers

Declaring that a function never returns

If I have a function that never returns (it contains an infinite loop) how do I declare/communicate that it will never return to the user of the function? The user does not see the source code, only ...
Fred's user avatar
  • 489
21 votes
4 answers

MVC and RESTful API service

MVC is pretty straightforward. There is a Model, a Controller and a View. When we create a website, it all come together as 'client sends REST keyword request to server -> the server matches the ...
simon's user avatar
  • 369
20 votes
5 answers

Is it bad practice to use hyphens in JSON keys?

I see a lot of questions revolving around accessing JSON keys that use hyphens (kebab-case), but now I find myself wondering should I just stick to camelCase or snake_case in my keys. I know hyphens ...
Matt Oaxaca's user avatar
20 votes
2 answers

Should one always know what an API is doing just by looking at the code?

Recently I have been developing my own API and with that invested interest in API design I have been keenly interested how I can improve my API design. One aspect that has come up a couple times is (...
markmnl's user avatar
  • 727
20 votes
2 answers

Is it bad practice to use a single endpoint to do multiple similar tasks?

So the scenario is that I'm asked to redesign and refactor a REST API by combining multiple endpoints that do similar tasks. For example, now I have 10 different endpoints that are all used to upload ...
lincredibleJC's user avatar
20 votes
1 answer

Why were Null-Safe Operators (e.g. "Elvis operator") rejected as part of Java 7's "Project Coin"?

One of the proposed features for Java 7's "Project Coin" was the "Elvis operator". A report of a 2009 JavaOne presentation on Project Coin described it as such: One of the "small features" covered ...
Thunderforge's user avatar
  • 2,718
20 votes
3 answers

Should I be permissive of unknown parameters?

I'm designing a RESTful API and faced with the title problem, restated for clarity: Should I fail fast if a client sends an unrecognized parameter? For example,
rath's user avatar
  • 886
19 votes
4 answers

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, ...
officer's user avatar
  • 309

2 3 4 5