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
184 votes
4 answers
75k 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 ...
user avatar
  • 2,834
111 votes
5 answers
74k 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 (...
user avatar
  • 2,608
45 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 ...
user avatar
  • 1,644
20 votes
8 answers
2k 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
94 votes
8 answers
73k 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 ...
user avatar
  • 1,099
30 votes
3 answers
19k 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
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 ...
user avatar
  • 3
8 votes
4 answers
4k 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 - ...
user avatar
  • 173
7 votes
3 answers
4k 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 ...
user avatar
  • 173
4 votes
2 answers
2k 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 ...
user avatar
  • 201
4 votes
2 answers
9k 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, ...
user avatar
  • 149
0 votes
1 answer
501 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: ...
user avatar
  • 193
0 votes
2 answers
178 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 ...
user avatar
  • 219
339 votes
14 answers
91k 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 -> ...
user avatar
  • 2,987
187 votes
7 answers
113k 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 ...
user avatar
  • 2,286
49 votes
3 answers
37k 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' ...
user avatar
  • 2,053
47 votes
2 answers
63k 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,...
user avatar
  • 581
18 votes
2 answers
17k 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: /...
user avatar
31 votes
4 answers
10k 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: ...
user avatar
  • 419
57 votes
1 answer
70k 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 ...
user avatar
  • 898
34 votes
3 answers
52k 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 ...
user avatar
15 votes
6 answers
1k 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 ...
user avatar
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 ...
user avatar
  • 259
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 ...
user avatar
  • 1,329
19 votes
3 answers
19k 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 ...
user avatar
  • 969
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 ...
user avatar
  • 629
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 ...
user avatar
8 votes
3 answers
3k 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 ...
user avatar
  • 898
2 votes
1 answer
1k views

Gradual reveal in REST APIs [closed]

In the article Building Web Services the REST Way, the author states: Design to reveal data gradually. Don't reveal everything in a single response document. Provide hyperlinks to obtain more ...
user avatar
  • 139
12 votes
5 answers
2k 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 ...
user avatar
11 votes
2 answers
9k 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 ...
user avatar
  • 275
8 votes
1 answer
6k 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 ...
user avatar
  • 569
7 votes
5 answers
4k 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 ...
user avatar
  • 181
3 votes
3 answers
1k 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 ...
user avatar
1 vote
3 answers
5k views

Checking for the presence of optional properties of an object

I'm designing a class that holds several types of data. Some of the properties are optional. For example, let's say I have a class that represents a person, and one of the properties is occupation. ...
user avatar
  • 1,644
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 avatar
  • 2,693
8 votes
4 answers
713 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;...
user avatar
6 votes
3 answers
1k 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 ...
user avatar
4 votes
2 answers
3k 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 ...
user avatar
  • 2,463
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 ...
user avatar
  • 5,956
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/...
user avatar
  • 241
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 ...
user avatar
  • 614
1 vote
2 answers
427 views

In my permissions API, how do I handle objects that don't exist?

Elgg is designing a permissions API loosely around the Activity Streams model. The user API could look (roughly) like: function elgg_can($capability, $subject = null, $object = null, $target = null) {...
user avatar
1 vote
8 answers
3k views

Is there a use case for boolean parameters? [closed]

Most programmers (including me) believe that methods with a boolean flag parameter should be refactored into two methods without the flag parameter. Are there any use cases for a boolean parameter ...
user avatar
  • 561
0 votes
1 answer
754 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 ...
user avatar
  • 149
10 votes
1 answer
5k 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. ...
user avatar
4 votes
2 answers
2k 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/...
user avatar
  • 169
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: '.....
user avatar
2 votes
1 answer
390 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 ...
user avatar
  • 3,336
2 votes
1 answer
427 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 ...
user avatar
  • 570