Document Properties
Kbid
3M0702
Last Modified
11-Jan-2023
Added to KB
11-Jan-2023
Public Access
Everyone
Status
Online
Doc Type
References
Product
  • IOM 3.1
  • IOM 3.2
  • IOM 3.3
  • IOM 3.4
  • IOM 3.5
  • IOM 3.6
  • IOM 3.7
  • IOM 4.0
  • IOM 4.1
  • IOM 4.2
  • IOM 4.3
  • IOM 4.4
  • IOM 4.5
  • IOM 4.6
  • IOM 4.7
  • IOM 5.0
Reference - IOM REST API - Reservation

Introduction

This reference is intended for developers and lists available endpoints of the IOM Reservation REST API.


Get Stock Reservation

URI

servlets/services/reservation/<resvId>

Http Method

GET

Short Description

Used to get a stock reservation. Usually called to check the validity of a stock reservation.

Example Requests URL

http://10.17.0.245:8080/servlets/services/reservation/117

Example RequestsNo Content

HTTP Status Codes

  • 200 OK
  • 400 Bad Request

  • 401 Unauthorized

  • 404 Not Found

  • 500 Internal Server Error

Description

The IOM enables shop systems to get stock reservations via HTTP GET requests via ID.

This service supports only the content-type application/json.

ParametersPath parameter resvId = ID of the requested stock reservation

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>' \
--method=get http://<hostname>/servlets/services/reservation/117
It is Important that the permission REST_RESERVATION (oms.RightDefDO with ID = 124 and name "Reservation REST service") is assigned to the requesting user. The permission is a part of the class bakery.persistence.dataobject.configuration.common.RightDefDO.
The user also needs the permission for the OMS shop instance which relates to the requested stock reservation.

JSON

Request data format

application/json

Request related java object

n/a

Request data example

No Content

Response data format

application/json

Response related java object

bakery.webservice.rest.v1.HttpResponse
bakery.reservation.v2.ReservationResponse as "data" object
Response Attributes
AttributesDescription
statusCodeHTTP status code

errors

always empty

exceptions

always empty
datasee table below
Data AttributeDescription
validUntilThe Validity of the Stock Reservation
resvIdThe id <primary key> of the Stock Reservation
items1..n items. See table below
Item AttributeDescription
idThe ID of the product. Via the OMS configurations it is determined if it is the shop product number or the IOM product ID.
qtyReserved quantity
state

State of the reservation. The reservation of the product is still "revered" or "expired".

Response data example

{
  "errors": [
  ],
  "statusCode": 200,
  "exceptions": [
  ],
  "data": {
    "validUntil": "2016-01-06 15:05:30",
    "resvId": 118,
    "items": [
      {
        "id": "First-Test",
        "qty": 3,
        "state": "reserved"
      },
      {
        "id": "First-Test",
        "qty": 2,
        "state": "reserved"
      }
    ]
  }
}
Response Code200


Update Stock Reservation

URI

servlets/services/reservation/<resvId>

Http Method

PUT

Short Description

Update a stock reservation.
Example Requests URLhttp://10.17.0.245:8080/servlets/services/reservation/130

Example Requests

{ "lifetime": 60, "items": [ { "id": "First-Test", "qty": 7 } ] }

HTTP Status Codes

  • 201 Created
    Stock reservation suspenseful updated

  • 400 Bad Request
    There is no reservation in the OMS system for parameter resvId or in the case of a semantic or syntactic error.

  • 401 Unauthorized

  • 404 Not Found

  • 500 Internal Server Error

Description

This PUT method updates an existing stock reservation. Unlike the POST method to create a new reservation, this method updates specific information of an existing stock reservation. You can update the validity of a reservation. You can remove already reserved products from a reservation or add other products (reservation items). Furthermore, the reserved quantity of an already reserved product can be changed.

If the reservation is already expired  each product reservations will be removed and the OMS perform the creation of new reservation items like the POST method it does. At the response appears an exception with code 21004 and message " The reservation with id <resvId> has already expired".

This service only supports and accepts requests with content-type application/json.

ParametersPath parameter resvId = ID of the existing IOM reservation - Example = 130

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>' \
--method=put --body-data='{"lifetime":60, "items":[{"id":"First-Test", "qty":7}]}' \
http://<hostname>/servlets/services/reservation/130

It is Important that the permission REST_RESERVATION (oms.RightDefDO with ID = 124 and name "Reservation REST service") is assigned to the requesting user. The permission is a part of the class bakery.persistence.dataobject.configuration.common.RightDefDO.

The user also needs the permission for the IOM shop instance which relates to the requested stock reservation.

Concurrency

To avoid overbooking of products the OMS checks the current inventory of the product before storing the reservation. The inventory check itself depends on stock reservations. For this reason the OMS uses database advisory locks to serialize the requests.

If it is not possible for a request to obtain all locks for the products to reverse within five seconds, the client gets a response with HTTP status code 500 and the following payload:

{
  "data": null,
  "statusCode": 500,
  "errors": null,
  "exceptions": [{
      "code": "500",
      "message": "bakery.util.exception.TechnicalException: Technical error while working on object 'ReservationPersistenceBean': 
			Unable to update reservation. Cannot get the necessary database lock to perform a concurrent safe inventory check."
    }]
}

JSON

Request data format

application/json

Request related java object

bakery.v2.reservation.ReservationRequestImpl
Request Attributes
Attribute
Description
TypeNullable
lifetime

The lifetime / validity of the stock reservation in seconds.Max value is 2147483647.
Greater values creates a response with HTTP status code 400 caused by a JsonParseException.

Default is 10 minutes.

Omitting of this attribute leads to an update of the validity to 10 minutes.

Integertrue
type

The reservation type:

  • COMPLETE = products are only reserved if all products of the request are reservable

  • PARTLY = products are reserved, even when one or more of the reserved products are not reservable.

If type is missing the OMS uses COMPLETE. All values unequal COMPLETE be interpreted as   PARTLY .

Stringtrue
items1..n products to reserve. For details see table below.Arrayfalse
Item Attribute
Description
TypeSizeNullable
idThe ID of the product. Via the IOM configurations it is determined if it is the shop or IOM product IDString30false
qtyReserved quantityInteger
false
Request data example
{
  "lifetime": 180,
  "items": [
    {
      "id": "First-Test",
      "qty": 7
    }
  ]
}

Response data format

application/json

Response related java object

bakery.webservice.rest.v1.HttpResponse
bakery.reservation.v2.ReservationResponse as "data" object
Response Attributes
AttributesDescription
datasee table below
statusCodeHTTP status code
errorsempty in case of successful processing. For details see Response Attribute Errors
exceptionsempty in case of successful processing. For details see Response Attribute Exceptions
Data Attributes
Description
validUntilThe validity of the stock reservation
resvIdThe ID <primary key>  of the stock reservation
items1..n items. See table below
Item Attributes
Description
idThe ID of the product. Via the IOM configurations it is determined if it is the shop product number or the oms product ID.
qtyReserved quantity
stateState of the reservation.  
The reservation of the product is still "revered" or "expired".

Response Attribute Errors

Source Field
Message
items.qtyCan not construct instance of int from String value 'value from request': not a valid integer value

HTTP status code = 400

Response Attribute Exceptions
Code
DescriptionHTTP status code
JsonParseExceptionFor each not well formed JSON request payload 400
CODE_21001The product to be reserved was not found400

CODE_21004

The reservation has already expired

201 if the update is successful,

otherwise 400

Response data example

{
  "data": {
    "validUntil": "2016-01-07 14:29:32",
    "resvId": 130,
    "items": [
      {
        "id": "First-Test",
        "qty": 7,
        "state": "reserved"
      }
    ]
  },
  "statusCode": 201,
  "errors": [
  ],
  "exceptions": [
  ]
}
Response Code201


Create Stock Reservation

URI

servlets/services/reservation/<shopId>

Http Method

POST

Short Description

Create a stock reservation.
Example Requests URLhttp://10.17.0.245:8080/servlets/services/reservation/10010

Example Requests

{ "lifetime": 180, "type": "COMPLETE", "items": [ { "id": "First-Test", "qty": "2" } ] }

HTTP Status Codes

  • 201 Created

  • 400 Bad Request

  • 401 Unauthorized

  • 404 Not Found

  • 500 Internal Server Error

Description

This service creates stock reservations for a given OMS shop instance. A stock reservation is a list of reserved products with the appropriate amount. Each stock reservation has a validity which can be set by the field lifetime at the request payload.

The response provides a status code 201 on success with the reserved products, the state of the reservation and a unique reservation reference ID.

This service only supports and accepts requests with content-type application/json.

ParametersPath parameter shopId = ID of the OMS shop instance - Example = 10010

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>' \
--method=post --post-data='{"lifetime":180, "type":"COMPLETE", "items":[{"id":"First-Test", "qty":"2"}]}' \
http://<hostname>/servlets/services/reservation/10010
It is Important that the permission REST_RESERVATION (oms.RightDefDO with ID = 124 and name "Reservation REST service") is assigned to the requesting user. The permission is a part of the class bakery.persistence.dataobject.configuration.common.RightDefDO.

The user also needs the permission for the OMS shop instance which relates to the requested stock reservation.

Concurrency

To avoid overbooking of products the OMS checks the current inventory of the product before storing the reservation. The inventory check itself depends on stock reservations. For this reason the OMS uses database advisory locks to serialize the requests.

If it is not possible for a request to obtain all locks for the products to reverse within five seconds, the client gets a response with HTTP status code 500 and the following payload:


JSON

Request data format

application/json

Request related java object

bakery.v2.reservation.ReservationRequestImpl

Request Attributes

Attribute

Description

Type

Nullable

lifetime

The lifetime / validity of the stock reservation in seconds.Max value is 2147483647.
Greater values creates a response with HTTP status code 400 caused by a JsonParseException,

Default is 10 minutes.

Integer

true

type

The reservation type:

  • COMPLETE = products are only reserved if all products of the request are reservable

  • PARTLY = products are reserved, even when one or more of the reserved products are not reservable

If type is missing the OMS uses COMPLETE. All values unequal COMPLETE be interpreted as PARTLY.

String

true

items

1..n products to reserve. For details see table below.

Array

false

Item Attribute

Description

Type

Size

Nullable

id

The ID of the product. Via the OMS configurations it is determined if it is the shop or oms product ID.

String

30

false

qty

Quantity to reserve

Integer


false

Request data example


Response data format

application/json

Response related java object

bakery.webservice.rest.v1.HttpResponse

bakery.reservation.v2.ReservationResponse as "data" object

Response Attributes

Attributes

Description

data

see table below

statusCode

HTTP status code

errors

empty in case of successful processing. For details see Response Attribute Errors

exceptions

empty in case of successful processing. For details see Response Attribute Exceptions

Data Attributes

Description

validUntil

The Validity of the Stock Reservation

resvId

The id <primary key> of the Stock Reservation

items

1..n items. See table below

Item Attributes

Description

id

The ID of the product. Via the OMS configurations it is determined if it is the shop product number or the oms product ID.

qty

Reserved quantity

state

State of the reservation.
The reservation of the product is still "revered" or "expired".

Response AttributeErrors

Source Field

Message

items.qty

Cannot construct instance of int from String value 'value from request': not a valid Integer value

HTTP status code= 400

Response AttributeExceptions

Code

Description

JsonParseException

For each not well formed JSON request payload

CODE_21001

The product to be reserved was not found

CODE_21003

We don't have enough stock for requested product

HTTP status code= 400

Response data example

{
  "data": {
    "validUntil": "2016-01-07 15:03:36",
    "resvId": 119,
    "items": [
      {
        "id": "First-Test",
        "qty": 2,
        "state": "reserved"
      }
    ]
  },
  "statusCode": 201,
  "errors": [
  ],
  "exceptions": [
  ]
}

Response Code

201


Remove Stock Reservation

URI

servlets/services/reservation/<resvId>

Http Method

DELETE

Short Description

Remove a stock reservation.

Query Parameters

none

Example Requests

http://10.17.0.245:8080/servlets/services/reservation/115

HTTP Status Codes

  • 204 No Content
    Stock reservation suspenseful removed
  • 400 Bad Request
    there is no reservation in the OMS system for parameter resvId

  • 401 Unauthorized

  • 404 Not Found

  • 500 Internal Server Error

Description

Remove Stock Reservation - API

Used by shop systems to delete an existing stock reservation from the IOM system.

Parameters  Path parameter resvId = ID of the stock reservation to be deleted

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>' \
--method=delete http://<hostname>/servlets/services/reservation/115
It is Important that the permission REST_RESERVATION (oms.RightDefDO with ID = 124 and name "Reservation REST service") is assigned to the requesting user. The permission is a part of the class bakery.persistence.dataobject.configuration.common.RightDefDO.
The user also needs the permission for the OMS shop instance which relates to the requested stock reservation.

JSON

Request data format

No Content

Request related java object

n/a

Request data example

n/a

Response data format

No Content

Response related java object

n/a

Response data example

n/a
Response Code204

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.
The Intershop Knowledge Portal uses only technically necessary cookies. We do not track visitors or have visitors tracked by 3rd parties. Please find further information on privacy in the Intershop Privacy Policy and Legal Notice.
Home
Knowledge Base
Product Releases
Log on to continue
This Knowledge Base document is reserved for registered customers.
Log on with your Intershop Entra ID to continue.
Write an email to supportadmin@intershop.de if you experience login issues,
or if you want to register as customer.