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
205 votes
4 answers
95k views

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
115 votes
5 answers
87k views

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
46 votes
6 answers
7k views

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
24 votes
11 answers
3k views

"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
98 votes
8 answers
78k views

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
32 votes
3 answers
20k views

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
12 votes
2 answers
20k views

How to specify many ids and their variable name in a REST API request?

What is the most common and wise way to specify many entities' ids in an API request? For a singular entity request I have: GET /v1/entities/{entity_id} My suggestions for requesting many entities: ...
Yann's user avatar
  • 573
8 votes
4 answers
5k views

What HTTP status using for REST search query which returns nos results

I'm wondering how to manage empty results returned by search queries in a REST web-service : I there was a query like my_ressource_collection/{id} and the resource didn't exists i would return 404 - ...
Sylvain's user avatar
  • 173
7 votes
3 answers
5k views

How to handle business rules with a REST API?

I have a REST API to manage a booking system I'm searching how to manage this situation : A customer can book a time slot : A TimeSlot resource is created and linked to a Person resource. In order to ...
Sylvain's user avatar
  • 173
5 votes
2 answers
10k views

validation error responses in REST API

I'm designing a RESTful API and wondering what's the best format for validation error messages. For example, my account creation endpoint accepts a JSON object: user: { first_name: string, ...
sean hawk's user avatar
  • 159
4 votes
2 answers
3k views

REST API Structure to request multiple items

I have a REST API that looks something like the below where a person can belong to an organisation (but doesn't have to) and a person has many items. The items may also belong to the organisation ...
Jamie's user avatar
  • 201
0 votes
2 answers
233 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 access to ...
Creepin's user avatar
  • 219
0 votes
1 answer
4k views

REST API design for associations/aggregation

I am building RESTful API that manages persons and lists. There can be many List and many Person each with its own set of properties. Person can be in zero or more lists, List can contain zero or more ...
Gustas's user avatar
  • 3
0 votes
1 answer
642 views

How to API design architecture for long delay process

Im trying to start an API design using Django Rest Framework, and the problem Im trying to solve is the following: Request endpoint is like this: POST http://server:8080/api/v1/device attribute: ...
gogasca's user avatar
  • 193
341 votes
14 answers
93k views

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
203 votes
7 answers
127k views

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
64 votes
1 answer
77k views

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
58 votes
3 answers
44k views

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
50 votes
2 answers
83k views

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
34 votes
3 answers
60k views

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
32 votes
4 answers
12k views

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
19 votes
3 answers
22k views

Should backend IDs be public or not on a REST API?

Based on what this guy says: http://toddfredrich.com/ids-in-rest-api.html Let assume he is right about using UUID to identify the api resources. Then I run into troubles trying to implementing it ...
anat0lius's user avatar
  • 1,019
19 votes
2 answers
18k views

When to use nested resources in a RESTful API

I have two resources: users and links. Users can have several links associated with them. I have designed my RESTful API so that you can reach the links associated with a user at the following URI: /...
Oliver Joseph Ash's user avatar
17 votes
6 answers
5k 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 ...
gaugau's user avatar
  • 311
15 votes
3 answers
3k views

Versioning REST APIs. Each API has its own version

It's very common to specify the version of REST APIs in the URL, specifically at the beginning of path, i.e. something like: POST /api/v1/accounts GET /api/v1/accounts/details However, I haven't ...
Eng.Fouad's user avatar
  • 259
15 votes
6 answers
2k views

What do great APIs have in common? [closed]

What is it about great APIs that makes them great? I think that adhering to the "do one thing and do it well" mantra is a good sign and being is a good mapping to the problem domain is important, but ...
dan_waterworth's user avatar
11 votes
2 answers
11k views

What is a proper response status code to POST when parent resource is not found?

I've the following endpoint: a/{id}/b and want to create a b with sending POST request to it. If a with given {id} is not found should I response with 404 NOT_FOUND or maybe with 409 CONFLICT? It ...
Opal's user avatar
  • 275
11 votes
1 answer
6k views

Is it bad to use POST only on an API?

I'm about to develop a new API for our website. Part of the design I've considered to use the POST and GET methods but after reading some security stuff I realise that GET is a bit less secure(i.e. ...
The user with no hat's user avatar
9 votes
3 answers
4k views

REST API design: POST (implicit userId) vs PUT (explicit userId)

For some routes on an API, like GET /news, one would asume the user only wants news that pertains to them, so the userId is implicitly taken from authentication info. However, some of the routes on ...
jtmarmon's user avatar
  • 978
9 votes
2 answers
4k views

Is implementing an interface defined in a subpackage an anti-pattern?

Let's say I have the following: package me.my.pkg; public interface Something { /* ... couple of methods go here ... */ } and: package me.my; import me.my.pkg.Something; public class SomeClass ...
user's user avatar
  • 2,713
9 votes
1 answer
7k views

Sending a collection of data to an API. Multiple small calls vs one big call

I am currently creating an API and implemented a few basic REST actions such as get, update, search etc. Another program that collects data needs to synchronize these to this API. My current thought ...
pdu's user avatar
  • 579
9 votes
2 answers
2k views

Partitioning REST API resources into areas based on business domains

In a major application REST API that covers several related domains, does it make more sense to split resources into 'areas' based on the business domain they belong to or is it better to to maintain ...
astreltsov's user avatar
8 votes
2 answers
2k views

What layer to introduce human readable error messages?

One of the things that I have never been happy with on any project I have worked on over the years and have really not been able to resolve myself is exactly at what tier in an application should ...
MrLane's user avatar
  • 629
8 votes
4 answers
773 views

Dependency Inversion expands the API, results in unnecessary tests

This question has bothered me for a few days, and it feels like several practices contradict each other. Example Iteration 1 public class FooDao : IFooDao { private IFooConnection fooConnection;...
Chris Wohlert's user avatar
7 votes
5 answers
6k views

Bulk update: return all results or only failures

I'm developing an API that performs bulk update of a large number of items in a single call. This code will consist of a REST endpoint and the internal library code that it calls. There are a few ...
Jack A.'s user avatar
  • 181
7 votes
3 answers
15k views

Should I use both WCF and ASP.NET Web API

We already have a WCF API with basichttpbinding. Some of the calls have complex objects in both the response and request. We need to add RESTful abilities to the API. at first I tried adding a ...
Mithir's user avatar
  • 1,339
7 votes
2 answers
4k views

How to handle fine grained field-based ACL permissions in a RESTful service?

I've been trying to design a RESTful API and have had most of my questions answered, but there is one aspect of permissions that I'm struggling with. Different roles may have different permissions ...
Jason McClellan's user avatar
6 votes
1 answer
2k views

Why should I map external IDs to internal IDs in my API?

We have a public API. Users will call this API by passing in different Guids as the IDs for entities. In the API, the Guid will be translated to the internal ID (Int32) for that particular record in ...
David Klempfner's user avatar
6 votes
3 answers
2k views

Domain-Driven Design: Cross-Domain Search

I have two systems (for sake of example, and orders and an account domain). Their interfaces consist of an api per system (an orders api and an account api). I have a UI that is sitting on top of ...
JohnsonCore's user avatar
5 votes
2 answers
6k views

REST API: POST and PUT for nested resources

I am wondering how to deal with nested resources in a REST API. I've seen other questions on the subject here, but I didn't find one that answered my question. More specifically, should POSTing/...
samdouble's user avatar
  • 243
4 votes
2 answers
4k views

Are different endpoints to display the same resource in different ways RESTful?

Say I have a Student who has a ID number, a name, a profile picture, some contact details, and is enrolled in several courses. From the perspective of a Single Page Application there are different ...
dwjohnston's user avatar
  • 2,563
4 votes
3 answers
1k views

API method placement guidelines?

Are there any guidelines for placing methods in API when the placement isn't obvious? Example: I have classes A and B and a method X. The work being carried out can be phrased in two ways: A does X ...
Andy Hunt's user avatar
  • 6,036
4 votes
3 answers
2k views

What are the "best practice" to manage related resource when designing REST API?

When designing REST API I generally start by identifying the resource of my system, to give an example let's say that we manage multiple blogs, each one with multiple posts, each one with multiple ...
heapOverflow's user avatar
3 votes
4 answers
5k views

Should the admin application consume the API, or should it access the DB directly?

I will be developing a mobile app, which will mainly act as a client. There will be an API on the cloud that these mobile clients will interact with, and there will also be a web application for ...
hattenn's user avatar
  • 211
3 votes
2 answers
2k views

REST API update child reference

I'm working on a project where we are creating some REST APIs My question is when we are creating an API to update an entity that contains a children reference, i.e. { name: '...', email: '.....
Charlie Wu's user avatar
3 votes
1 answer
2k views

Extending ACL with more sophisticated rules in web REST API

I am currently working a REST API design and I am looking for a way to add an advanced ACL management, beyond what Let's consider for instance that I have a route which is the following : /profile/...
ibi0tux's user avatar
  • 241
3 votes
3 answers
4k 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 ...
Alex's user avatar
  • 141
2 votes
1 answer
463 views

How to structure your URIs?

I am making a web UI and an HTTP API for editing JSON documents in collaboration (role and versioning system). There are several types of JSON documents. Each type is described by a JSON schema, let ...
Géry Ogam's user avatar
2 votes
2 answers
2k views

Should I use HTTP search

I am working on a web api and I am curios about the HTTP SEARCH verb and how you should use it. My first approach was, well you could use it surely for a search. But asp.net WebApi doesn't support ...
Knerd's user avatar
  • 624
2 votes
1 answer
396 views

Protecting API Keys

Iv'e moved this from SO as it's more of a design question than a code one. In many applications third party websites/programs can access the website via a key. For example, a web application hosts ...
Liath's user avatar
  • 3,436