Web API - correct response to client

Question

We have the following format of response to client if request is successful:

{
  "ExitCode": 1,
  "ErrorMessage": "",
  "NumberOfGreenBoxMatches": 4,
  "NumberOfPinkBoxExtractFrames": 5,
  "ProcessingTime": 4000,
  “HasOverlay”: false;
  "MatchResult": "...."
}

If a client request is bad or internal error is happened customer proposes to return the following:

{
  "ExitCode": -10,
  "ErrorMessage": "Internal error parsing pink boxes. Please contact tech support",
  "NumberOfGreenBoxMatches": 0,
  "NumberOfPinkBoxExtractFrames": 0,
  "ProcessingTime": 1240,
  “HasOverlay”: false;
  "MatchResult": ""
}

is it correct approach (return the similar json)? My opinion is no, we should return only like

{ "ErrorMessage": "Internal error parsing pink boxes. Please contact tech support" }

and correct HttpCode. What is correct way?

Alexander Yancharuk · Accepted Answer · 2017-06-02 09:25:58Z

2

Your suggestion about correct approach looks more HTTP-standart compatible. Because ExitCode looks like HTTP-response codes functionality duplication.

But final solution i think is highly depends on client architecture. There is some questions that you must take into account:

Does client parse HTTP codes?
How client validates server responses?
Does server error-responses MUST be JSON-schema compatible with regular responses?
Does your client must always receive values in fields like ProcessingTime etc.

answered Jun 2, 2017 at 9:25

Alexander Yancharuk

14.7k5 gold badges60 silver badges57 bronze badges

Sign up to request clarification or add additional context in comments.

5 Comments

Oleg Sh Over a year ago

How implements multilanguage in such way?

Alexander Yancharuk Over a year ago

@OlegSh you should implement Accept-Language: header on client side. You can use that header in request for multilangual error messages.

Oleg Sh Over a year ago

ok, with multilanguage I agree. But there are many situations when need to have an additional 'exitcode'. I.e. user did not select an image and application should show special form for it...

Alexander Yancharuk Over a year ago

@OlegSh Question case describes situation with one server-side fatal error. If you need to inform client about multiple errors (like multi-field form validation errors) just use errors field with errors array.

Oleg Sh Over a year ago

I don't mean multiple error. I mean, so, error can be "Invalid something" and "File is not uploaded" (both are bad request). In the first case we want to display a message with error, in the second - show File Upload dialog. So, we have to separate what is the problem on client part. We can do it using additional error code, because we can't do it by error message...

Pranesh Janarthanan · Accepted Answer · 2017-06-02 09:37:58Z

-1

The result from Web API is received using a Model, Here the Model used in Client side is

public class MyResult
{
    public int ExitCode { get; set; }
    public string ErrorMessage { get; set; }
    public int NumberOfGreenBoxMatches { get; set; }
    public int NumberOfPinkBoxExtractFrames { get; set; }
    public int ProcessingTime { get; set; }
    public bool HasOverlay { get; set; }
    public string MatchResult { get; set; }
}

if you send a different result upon error, which has single property "ErrorMessage", They cannot process it on client side.

so you better provide the information as per the exact model proposed by your customer.

answered Jun 2, 2017 at 9:37

Pranesh Janarthanan

1,20220 silver badges28 bronze badges

5 Comments

Oleg Sh Over a year ago

status code says client that he should not process it as standard response

Pranesh Janarthanan Over a year ago

They can manage response based on information in it, for ex: As you pointed in Q, Exit Code : -10 . They can process the result based on this and display the error message.

Oleg Sh Over a year ago

they can, but HTTP requires return correct status code

Pranesh Janarthanan Over a year ago

then include one more property in the MyResult modal, public string StatusCode {get;set;} . Add the necessary data for each request. restapitutorial.com/httpstatuscodes.html

Pranesh Janarthanan Over a year ago

use try catch block, in catch use the MyResult modal as return, include error details with status code. but if your API is not reachable, your customer cannot expect the result like MyResult modal. Here they can use a validation like whether your API reachable before calling it.

Collectives™ on Stack Overflow

Web API - correct response to client

2 Answers 2

5 Comments

5 Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

5 Comments

5 Comments

Your Answer

Sign up or log in

Post as a guest

Related