Concept - REST API Error and Info Messages (v1)

Product Version

7.10

Product To Version


Status

final

1 Introduction

Commonly a server indicates the result of REST request processing by responding different HTTP status codes. This behavior is not sufficient for REST clients that interact with an end user in most cases. Therefore there should be a coherent approach to how additional information about causes of errors or server-side business logic decisions should be provided to a REST client.

At the time of writing not every REST API in ICM uses this pattern for error and info messages. Currently only the new basket and order APIs follow the approach outlined here. Future APIs or new versions of existing APIs should be designed with this in mind.

2 Glossary

TermDescription
RESTREpresentational State Transfer is an architectural style that defines a set of constraints and properties based on HTTP.
JSONJavaScript Object Notation - a human readable file format to transmit data using attribute-value pairs.

3 Error Messages

The REST-based storefront requires an error handling that is more sophisticated than providing only HTTP status codes:

  • Responding multiple failures as a result of a single request, e. g., basket validation failing for different reasons.
  • Addressing several attributes contained in the request's payload that have wrong values, e. g., if invalid values for firstName and zipCode have been provided in the context of a single address update request.
  • Providing invalid values together with valid limits or other information in the error message, e. g. value 4 is wrong; acceptable values: 5 to 10.

Those requirements cannot be met by a single HTTP response status code. Therefore any error message should provide the following information:

  • status - [mandatory] The HTTP status code applicable to this problem.
  • code - [mandatory] A unique identifier for this particular occurrence of the problem that may be used for localization on client side.
  • message - [mandatory] Human readable message in the locale contained in the request. The server may fall back to providing a message in its lead locale if the requested locale is not supported.
  • causes - [optional] An array of several other errors that caused the main one.
  • parameters - [optional] Several parameters that are used to assemble the message or which give further information to the client.
  • paths -  [optional] An array of JSON Path(s) [JsonPath] to the associated entity in the request document. If there is more than one path, then there is a relationship among the entities addressed by these paths, e. g., if the values specified for postal code and city do not match.
Structure of the Response Payload
{
    "data": [],
    "errors": [
        {
            "status": "422",
            "code": "basket.add_line_item_not_successful.error",
            "message": "The product could not be added to your cart.",
            "causes": [
                {
                    "code": "basket.line_item.add_item_max_item_quantity_exceeded.error",
                    "message": "The product quantity for this item in your shopping cart has exceeded our Maximum Purchasing Policy.",
                    "parameters": {
                        "sku": "4852562"
                    }
                }
            ],
            "paths": [
                "$[0]"
            ]
        }
    ]
}

4 Info Messages

Besides information about errors there are other use cases for providing information about the processing of the request to a REST client. This functionality is mainly required by REST API for process-driven functionalities like basket handling, checkout and payment. The structure for info messages is similar to error messages.

Example: The user changes the quantity of a basket item from a value equal to 1 to 99. The REST-based storefront publishes this change via a PATCH request to the server. The server processes the request successfully, but adjusts the item's quantity finally to a value equal to 50, because this value is configured as maximum quantity for an item. The REST-based client has to inform the user about the adjustment.

Structure of the Response Payload
{
    "data": {
        // ...
        "quantity" : 50,
        // ...
    },
    "infos": [
        {
            "code": "basket.line_item.update.info",
            "message": "The line item could not or only partially be updated."
            "causes": [
                {
                    "code": "basket.line_item.update_item_max_item_quantity_exceeded.info",
                    "message": "The quantity you entered is invalid. We have adjusted the quantity to meet our Maximum Purchasing Policy.",
                    "parameters": {
                        "requested": "99",
                        "lineItemId": "qdYKAEsBenwAAAFunNkvHJKP",
                        "granted": "50"
                    },
                    "paths": [
                        "$.quantity"
                    ]
                }
            ]
        }
    ],
}

5 Discussion

The following aspects have to be considered:

  • Localization should be supported on server side (message) and client side (codeparameters) as well.
  • There is no need to inform the client in case the server provides the message in the lead locale if the locale requested by the client is not supported by the server.
  • Currently there is no special format/description language for parameters. However, the parameters should be described in the API reference documentation, because they are part of the API.

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Support Tickets