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.

  • magic_lobster_party@fedia.io
    18·
    2 months ago

    I think the general rule of thumb is: Keep it Simple, Stupid.

    Don’t include fields “just in case”. If you don’t have a use for a field right now, then don’t include it. It’s often easier to add fields than removing.

    Avoid having fields that can be derived from other fields. Code “UNAUTHORIZED” can be derived from 403. Having both adds confusion. It adds the question whether the code field be something other than “UNAUTHORIZED” when the response is 403.

    Just 403 with empty body is fine. Add message in a JSON in case it’s useful for the user. If the user needs more fields in the future, then it’s easy to expand the JSON.

    • huginn@feddit.it
      14·
      2 months ago

      403 is a category, not a code. Yes I know they’re called http codes but REST calls are more complex than they were in 2001. There are hundreds of reasons you might not be authorized.

      Is it insufficient permissions? Authentication required? Blocked by security? Too many users concurrently active?

      I’d argue the minimum for modern services is:

      403 category
      Code for front end error displays
      Message as default front end code interpretation

      As json usually but if you’re all using protobuf, go off King.

      • hexbatch@programming.dev
        1·
        2 months ago

        Yes, the more information and standards in an api response the better. There should be front end messages and developer messages. URL links to documentation are great too. Standards assist automation and testing.

        I understand other viewpoints about maintenance and redundancy, this can cause errors. And the above is too much work for some projects .

        But most api start as a temporary or one person project. It’s tempting to be terse and cool with responses . Even more tempting is this is a great cost cutter to not have overly detailed responses.

        However

        It’s much easier to add in more data to responses now than later. And a future you years later, or strangers who use it , will be grateful. It may be the thing that allows an api to be popular, rather than people use it despite the api