this post was submitted on 30 Aug 2024
131 points (99.2% liked)

Programming

17432 readers
299 users here now

Welcome to the main community in programming.dev! Feel free to post anything relating to programming here!

Cross posting is strongly encouraged in the instance. If you feel your post or another person's post makes sense in another community cross post into it.

Hope you enjoy the instance!

Rules

Rules

  • Follow the programming.dev instance rules
  • Keep content related to programming in some way
  • If you're posting long videos try to add in some form of tldr for those who don't want to watch videos

Wormhole

Follow the wormhole through a path of communities [email protected]

founded 1 year ago
MODERATORS
[email protected]
[email protected]
[email protected]
131
What is your preferred API error response and why? (lemy.lol)
submitted 2 months ago* (last edited 2 months ago) by [email protected] to c/[email protected]
87 comments fedilink hide all child comments
 

I prefer simplicity and using the first example but I'd be happy to hear other options. Here's a few examples:

HTTP/1.1 403 POST /endpoint
{ "message": "Unauthorized access" }

HTTP/1.1 403 POST /endpoint
Unauthorized access (no json)

HTTP/1.1 403 POST /endpoint
{ "error": "Unauthorized access" }

HTTP/1.1 403 POST /endpoint
{
  "code": "UNAUTHORIZED",
  "message": "Unauthorized access",
}

HTTP/1.1 200 (๐Ÿคก) POST /endpoint
{
  "error": true,
  "message": "Unauthorized access",
}

HTTP/1.1 403 POST /endpoint
{
  "status": 403,
  "code": "UNAUTHORIZED",
  "message": "Unauthorized access",
}

Or your own example.

(page 2) 37 comments
sorted by: hot top controversial new old
[โ€“] [email protected] 2 points 2 months ago

The last one is very convenient. As an API consumer you can get all the necessary info from the returned payload, and the 403 will trigger the error path.

[โ€“] [email protected] 2 points 2 months ago

A mix between the last one and the previous. The key error should be set in order to indicate the presence of an error, while status and code represents, respectively, the error numerical code and the error type, while the error message is supposed to be concatenated to an human-friendly error text.

[โ€“] [email protected] 2 points 2 months ago (4 children)

A simple error code is sufficient in all of these cases. The error provided gives no additional information. There is no need for a body for these responses.

load more comments (4 replies)
[โ€“] [email protected] 2 points 2 months ago

Of those options I'm going with the last one. Because you have the standard error number right there but I'm assuming that it's a customer response so the message could be modified to have something useful in it.

[โ€“] [email protected] 1 points 2 months ago

Anything except the 2nd to last one, which is, unfortunately, mandated by my employer's internal code style guidelines. ๐Ÿซ 

[โ€“] [email protected] 1 points 2 months ago

1, 3, 4 are good but out of laziness I'd personally use the first.

[โ€“] [email protected] 1 points 2 months ago

1 or 3; maybe 4.

With several assumptions made, ultimately, they're asking for json, and we should still return json, but what that looks like is up to you. It should be static enough that the person on the other end can write:

If json.grtnode(error) == "unauthorized access"
Do stuff

Ifnyour going to be changing the text with some regularity to contain relevant information for the error (eg, an item ID, that is now invalid), then consider a code/text and additional fields.

[โ€“] [email protected] 1 points 2 months ago* (last edited 2 months ago)

#4 for me.

Proper HTTP Status code for semantic identification. Duplicating that in the response body would be silly.

User-friendly "message" value for the lazy, who just wanna toss that up to the user. Also, ideally, this would be what a dev looks at in logs for troubelshooting.

Tightly-controlled unqiue identifier "code" for the error, allowing consumers to build their own contextual error handling or reporting on top of this system. Also, allows for more-detailed types of errors to be identified and given specific handling and recovery logic, beyond just the status code. Like, sure, there's probably not gonna be multiple sub-types of 403 error, but there may be a bunch of different useful sub-types for a 400 on a form submission.

[โ€“] [email protected] 0 points 2 months ago

That clown emoji would make me think the company has alt-right sympathies

[โ€“] [email protected] -4 points 2 months ago (1 children)

The clown, but flipped with a success field. If it is true then command succeeded, if it false something was wrong and there should be an error field as well.

HTTP codes should be used for the actual transport, not shoe-horned to fit the data. I know not everyone will agree with this, but we don't have to.

[โ€“] [email protected] 1 points 2 months ago (1 children)

The transport is usually TCP/IP tho. But nowadays QUIC is trying to make it UDP. HTTP is specifically an Application Layer Protocol from OSI model

[โ€“] [email protected] 1 points 2 months ago

What I meant was that if you are returning 404 for example when a user doesn't exist. You can't tell if the user doesn't exist or someone changed the API to remove the endpoint.

But forcing HTTP codes without a moment to think it through seems to be the new fad.

load more comments
view more: โ€น prev next โ€บ