Software Engineering Stack Exchange
Software Engineering Stack Exchange

Questions tagged [api-design]

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

Good APIs are easy to use, require less explanation, are not slow and integrate well with the languages and environments they were intended for. They are also forgiving of caller errors and report accurate, descriptive errors.

1119 questions
339
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 -> controller builds a model (calls a Manager that gets the…
NibblyPig
  • 2,995
  • 3
  • 16
  • 19
200
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 collection or element DELETE - Well, erm, delete…
Rob Baillie
  • 2,416
  • 2
  • 13
  • 12
196
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 it a clean separation from the undesirable…
knownasilya
  • 3,074
  • 3
  • 17
  • 16
130
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 should I implement something that allows arbitrary…
LoveProgramming
  • 1,159
  • 2
  • 8
  • 8
113
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 (and requesting 0 waffles is a waste of time). So…
Thunderforge
  • 2,668
  • 3
  • 23
  • 30
97
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 avoid since updating multiple client platforms is…
Miro Svrtan
  • 1,129
  • 1
  • 8
  • 6
74
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-party APIs - Services out of my control that…
williamg
  • 841
  • 1
  • 6
  • 4
70
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": "john doe"} And then the application will update…
seldon
  • 952
  • 1
  • 7
  • 13
62
votes
1 answer

null vs missing key in REST API Response

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 missing key: {"firstName": "Bob"}
jtmarmon
  • 958
  • 1
  • 8
  • 12
60
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 /v1/get/movies returns 2 rows from the table movie…
Andres SK
  • 703
  • 1
  • 5
  • 7
55
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: { "success": true, "data": { /*…
Šime
  • 669
  • 1
  • 3
  • 6
54
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' communication mechanism that allows the services to…
KidCode
  • 2,123
  • 4
  • 17
  • 13
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 entities, Game, Platform, ESRBRating, and…
greyfox
  • 869
  • 1
  • 8
  • 11
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 against things like null, undefined, boolean, etc.…
Adam Thompson
  • 1,243
  • 1
  • 9
  • 14
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 appropriate http code would be for this error? 503:…
Shaharyar
  • 865
  • 2
  • 7
  • 12
1
2 3
…
74 75