Best Practices For API Response Formats

[API Dev]

I have questions around api response formats. We have a couple of api's for our enterprise application - one of them being the user management api - /users/createUser, /users/enableUser, /users/deleteUser, /users/sendAccountInfo and the other being an api for batch processing - /jobs/<job-name>/trigger, /jobs/<job-id>/status, /jobs/<job-id>/abort. 

Below are the questions

1. Each of the above api's have various validation checks that fail at runtime. I think it would be good to define codes to enable clients to have simpler catch blocks. For e.g. the /users/createUser could fail with an error code as 1001 when there is already an user present in the system with the same user name. 

Similary there are different codes for each of the api responses irrespective of successful or failure scenarios. Do you see any issues with it?

2. Would having different formats of the api responses (in successful & failure scenarios) across the supported api's lead to problems? For e.g. Do you see any issues if the /users/createUser returns

{

"code":2005,

"message":["Requested action was processed successfully"]

}

but for successful completion the /jobs/<job-id>/status returns

{

"code":3005,

"status": "Failed"

}

while the /jobs/<job-id>/abort returns

{

"code":4005,

"message":["Requested action was processed successfully"]

}

There are multiple such scenarios. Are there any issues in maintaining different formats or in other words should we strive for keeping the response format consistent?

Thanks.

[Jørn Wildt]

 Special codes are fine - but do also respect the normal HTTP status codes.

Here's some inspiration: http://soabits.blogspot.dk/2013/05/error-handling-considerations-and-best.html and https://tools.ietf.org/html/rfc7807.

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+unsubscribe@googlegroups.com.
Visit this group at https://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

[Eduardo Cabezas López]

Hello all,

I was doing some research about the Problem Details for HTTP APIs in order to incorporate it an API but I I have some questions about it, and this looked like a good thread to ask ;)

For a start what would be the best practice to document the errors (problems in the linked standard)? I'm thinking especially of custom problems with extended attributes. I think that documenting it in swagger might become quite cumbersome if every potential problem for each response must be documented for each swagger, even if you might have some APIs sharing most of those problem definitions.

I checked Zalando's guidelines (http://zalando.github.io/restful-api-guidelines/#176) which uses this standard, but they only show the use of the plain problem object without any customization (Zalando's swagger.). 

 

Also you might have multiple problems types for the same HTTP code. I think the open API specification doesn't state explicitly that you cannot use an HTTP code multiple times in a response (does it?), but I tried to do so using the swagger online editor and I get a "duplicated mapping key" error message. So would there be any solution for this using the open API specification?

 

I also wonder if the standard would allowe to return multiple problems in a single response. For instance if you have multiple errors in a request that returns HTTP 400, but they are of different kinds (for instance one parameter goes over a threshold value but you are also missing mandatory parameters...) it could get painful for the client to get only one error at a time in the response.

Hopefully this can start some valuable discussion.

Thanks in advance.

[Henry Andrews (JSON Schema)]

I know this is an old thread, but I'm working on using Problem Details right now, and eventually plan to link JSON Hyper-Schemas for the responses.  This is more of a flexible runtime solution that could still be incorporated into documentation.  You could use regular JSON Schema as well to describe just the structure if you do not need any of hyper-schema's features.

thanks,

-henry

[Erik Wilde]

hello.

On Apr 7, 2018, at 20:17, 'Henry Andrews (JSON Schema)' via API Craft <api-...@googlegroups.com> wrote:

I know this is an old thread, but I'm working on using Problem Details right now, and eventually plan to link JSON Hyper-Schemas for the responses.  This is more of a flexible runtime solution that could still be incorporated into documentation.  You could use regular JSON Schema as well to describe just the structure if you do not need any of hyper-schema's features.

my guidance would be to see response details reused across APIs as an open and evolving value space, that you want to manage and make available. the problem response RFC doesn't establish a registry for extension types, but nothing keeps you from  establishing and running one yourself.

- imagine http://webconcepts.info/concepts/ as also listing these problem detail types. it would be whatever types you think should be made reusable in your org.

- https://tools.ietf.org/html/draft-wilde-registries-01 might be interesting to read if you want to dive deeper into why to use registries, what needs to be done, and how to do it.

cheers,

dret.

[Henry Andrews]

I'm generally in favor of registries, but I'm not sold on it for Problem Details.  It feels a bit like the One True Ontology problem in semantic web.  The amount of effort needed to standardize is substantial, particularly when dealing with extension fields which may carry fairly specific information.  I'd certainly be interested if someone got something off the ground, but as you know I'm familiar with the challenges of getting consensus, or just majority support, from even a small community regarding internet standards.  I cannot imagine trying to solve the error design challenges specific to my API while at the same time trying to build support for standardizing the error types.

I consider API-specific error RFC 7807 "type" URIs to identify resources in much the same way that the "normal" API resource URIs do.  And of course RFC 7807 "instance" URIs are actual accessible resources within the API.

I'd love for my resources, error or otherwise, to be broadly machine-recognizable, but really the only place where I see the need for that to be worth the cost (given current technology maturity levels) is IoT.

-henry

--
You received this message because you are subscribed to a topic in the Google Groups "API Craft" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/api-craft/EmKAzXDpQVk/unsubscribe.
To unsubscribe from this group and all its topics, send an email to api-craft+...@googlegroups.com.

[Erik Wilde]

hello henry.

On 2018-04-08 06:49, Henry Andrews wrote:
> I'm generally in favor of registries, but I'm not sold on it for Problem
> Details.  It feels a bit like the One True Ontology problem in semantic
> web.  The amount of effort needed to standardize is substantial,
> particularly when dealing with extension fields which may carry fairly
> specific information.  I'd certainly be interested if someone got
> something off the ground, but as you know I'm familiar with the
> challenges of getting consensus, or just majority support, from even a
> small community regarding internet standards.  I cannot imagine trying
> to solve the error design challenges specific to my API while at the
> same time trying to build support for standardizing the error types.

i think i agree on all of this. but to me, there is a crucial difference
between the "one true ontology" problem and the way it usually is
approached with registries. registries typically work with open
namespaces, i.e. people are still free to make up their specific models.
but if some community feels like something is worth getting
standardized, then they can do that, get it registered, and thus make it
discoverable.

it very well may be that such a registry would remain small. how much
people invest in standards usually is a direct function of the utility
of standardization. so if there is infrastructure and tooling in place
that does useful things with standardized values, then you might see
people investing in standardized values. if it's just the theoretical
exercise of "let's standardize because of yet unknown potential value in
the future", probably not as much.

this means that the landscape architects in API orgs are the ones that
influence the dynamics: if they support/build tooling/infrastructure
that does useful things in a more coherent landscape, things will evolve
in this way. if there is no incentive or value beyond standardization
for the sake of standardization, there will be little natural momentum.

to me, the best path to take is:

- make sure to allow paths of standardization.
- influence incentives by providing tooling/infrstaructure for the
things where standardization can create value.
- support standardization through platforms such as registries for those
cases where it provides value.

> I consider API-specific error RFC 7807 "type" URIs to identify resources
> in much the same way that the "normal" API resource URIs do.  And of
> course RFC 7807 "instance" URIs are actual accessible resources within
> the API.
> I'd love for my resources, error or otherwise, to be broadly
> machine-recognizable, but really the only place where I see the need for
> that to be worth the cost (given current technology maturity levels) is IoT.

we'll see. once again, i agree to all you're saying in principle. but
the mechanics here really are the usual "not invented here" mechanics,
right? sure everybody can go ahead and re-invent that specific part of
their API language. but the economics of that decision are influenced by
how much it costs to reinvent the wheel, and how easy it is to find
wheel parts that work well. and the economics also are influenced by the
value the org can get out of more people using the same wheels.

cheers,

dret.

--
erik wilde | mailto:erik....@dret.net |
| http://dret.net/netdret |
| http://twitter.com/dret |