Concept - IOM REST Web Services

1 Introduction

The Intershop Order Management (IOM) uses the Representational State Transfer (REST). The present concept gives some basic information about the IOM's REST service handling.

This concept is primarily intended for all developers implementing a project or working in the core product of IOM.

1.1 References

2 General

2.1 Authorization

IOM supports "basic http authentication" only. Please configure your clients to use this authentication method. A very simple method to send REST requests on the command line can be realized using wget. The example also shows, how to configure this client to use "basic http authentication" (--auth-no-challenge).

wget -q -O- --auth-no-challenge  --http-user=<user> --http-password='<password>' \
http://<hostname>/<REST URL>

Allowed HTTP Requests

The following requests show the general existing HTTP requests. Not all requests are needed for each service.

  • POST- Creates or updates a resource

  • PUT- Updates a resource

  • GET- Retrieves a resource or list of resources

  • DELETE- Delete a resource

2.2 Typical Server Responses

  • 200OK - The request was successful.

  • 201Created - The request was successful and a resource was created.

  • 204No Content - The request was successful but there is no representation to return (that is, the response is empty).

  • 400Bad Request - The request could not be understood or was missing required parameters.

  • 401Unauthorized - Authentication failed or user does not have permissions for the requested operation.

  • 403Forbidden - Access denied.

  • 404Not Found - Resource was not found.

  • 405Method Not Allowed - Requested method is not supported for the specified resource.

  • 503Service Unavailable - The service is temporary unavailable (e.g., due to scheduled platform maintenance). Try again later.

3 Response Examples

3.1 Response Envelope Example

All API responses will be returned by the following JSON envelope. Errors, and exceptions are only present if they occur.

200 OK
{
        "data": {
            "validUntil": "2014-12-19 11:25:00",
            "resvId": "sdfdk43ß445lksld0394",
            "items": [
                {
                    "id": "BDJs-3432",
                    "qty": 2,
                    "state": "reserved"
                },
                {
                    "id": "AFEz-5562",
                    "qty": 1,
                    "state": "reserved"
                }
            ]
        },
        "errors": [],
        "exceptions": []
    }

3.2 Data

The data section contains the resource object for a success, typically a status code 200.

3.3 Errors and Exceptions

The errorssection contains validation errors when a request fails. On a success, this data is empty.

Error messages
"errors": [
    {
        "message": "The value must be an integer",
        "sourceField": "qty"
    },
    {
        "message": "The reservation type is invalid",
        "sourceField": "type"
    },
    {
        "message": "required",
        "sourceField": "shop"
    },
]

The exceptionssection contains exceptions that are thrown when a request fails due to an invalid request or code error. On a success, this data is empty.

Exceptions
"exceptions": [
    {
        "code": "20001",
        "message": "The requested id BDJs-3432 was not found "
    },
    {
        "code": "20002",
        "message": "The requested shop 1 was not found "
    }
]

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