Customize Faults

Google Cloud Apigee
1

Current Situation

Apigee Edge sends faults to the client in a specific format: { fault: … }. This includes both proxy faults and platform faults (e.g. when a non-existing path is requested, or a Node.js proxy has not fully started).

We’ve decided to use a different format: { error: …, code: …, status: … }. We modified our proxies to follow that convention.

Platform faults are still delivered as { fault: … }. We do not have a list of possible platform faults, and also no list of possible proxy faults.

Our API clients (like mobile apps) have to check for both “error” and “fault” properties and parse different formats since we cannot know that platform faults will not happen. This is bad API design.

Desired Situation

We have a comprehensive list of all possible proxy and platform errors.

All possible faults are delivered as { error: …, code: …, status: … }. Our API clients only have to check for “error” property and parse a single format. Good API design.

Question

How do we get there :-)?

Notes.

A “catch-all-proxy” as suggested here only catches “not found” issues. We need full control of the format.

The obvious solution to use the { fault: … } format instead is very restrictive and not an option, for obvious reasons.

In fact, even the Edge { fault: … } format is inconsistent. The detail property sometimes has a “code” property and sometimes “errorcode”, sometimes with uppercase constants (CLASSIFICATION_FAILED), sometimes camel-case dot-separated (steps.oauth.v2.FailedToResolveAPIKey)

We are on-premise, but this is definitely something any API designer wants.

2

Hi Morris, good question.

But can you explain why the “catch-all” JS policy that @arghya das suggested in this answer (which you cited) is not sufficient? I don’t understand what you mean by “only catches ‘not-found’ issues.” Can you elaborate?

3

Sorry, the catch-all proxy is actually suggested here: https://community.apigee.com/questions/8072/modify-default-404-response-in-cloud-instance.html - in a “Not Found” scenario there is no proxy which could handle the error, so the suggestion is to create a proxy with base path /. It might be sufficient, IF we get a list of possible errors, and are sure that these are handled by the catch-all proxy. A shared error handling js policy makes perfect sense, but again only catches errors in the context of a proxy.