1. Order REST API

1.1. General Jeeshop REST principles

1.1.1. Methods

Method Operations

GET

Get a single resource or get a collection of resources.

POST

Create a new resource.

PUT

Update properties of an existing resource.

DELETE

Delete an existing resource.

HEAD

Check authentication credentials. (Only available on User resource)

The media-type of HTTP requests should be set to application/json.
The media-type of HTTP responses is always application/json unless binary content is requested (eg. deployment resource data), the media-type of the content is used.

Items relationships are always lazy loaded and must be explicitly requested to get them. (they are not eagerly fetched)

1.1.2. Authentication and authorization

Jeeshop REST API operations are protected by role based access. Therefore, most of REST operations require authentication.
Jeeshop authentication and authorization are managed using JaaS. See this documentation for details about Jeeshop JaaS configuration on Wildfly application server.
Currently, only Basic HTTP access authentication is documented, so you should include a Authorization: Basic ...== HTTP-header when performing requests to API methods which are not public.

For security purpose we only allow Basic Authentication in combination with HTTPS. See this documentation for details about Jeeshop SSL configuration on Wildfly application server.

Each REST operation documentation declares one or many roles which are required for method use :

  • admin - Role dedicated to admin / back office operations. (Typically, it has to be set on Jeeshop administrators accounts for Jeeshop-Admin application use)

  • user - Default role bound to Jeeshop users. (Every online store registered users have this role)

  • ALL - Public. Methods which declare this role are public. Authentication is not required for their use.

1.2. Order resource

Manages user orders.

1.2.1. Get user/all orders

URL

/rs/orders

Method

GET

Roles allowed

admin,user
When authenticated user has user role and but not admin one, fetches only user’s orders.
When user has admin role, all orders are returned.

Parameters
Name Mandatory Description

search (applicable for admin role only)

No

Search criteria. Value should match user’s login, first name, or last name or order’s id, transaction id

start

No

results start offset

size

No

results size

orderBy

No

sort criteria. Defaults to id.
Possible values are : id | owner (user lastname) | login | status | creationDate | _updateDate

isDesc

No

sort direction. Defaults to false.
Possible values are : true | false

status

No

order status.
Possible values are : CREATED | VALIDATED | PAYMENT_VALIDATED | CANCELLED | READY_FOR_SHIPMENT | SHIPPED | DELIVERED | RETURNED

skuId (applicable for admin role only)

No

id of sku related to order

enhanced (applicable for admin role only)

No

boolean flag to get enhanced order with static order configuration and catalog related items.
Possible values are : true | false

Response HTTP statuses

Code

Meaning

200

Success

Response Body

Unresolved directive in <stdin> - include::snippets/Order.list.json.adoc[]

1.2.2. Get orders count

URL

/rs/orders/count

Method

GET

Roles allowed

admin

Parameters
Name Mandatory Description

search

No

Search criteria. Value should match user’s login, first name, or last name or order’s id, transaction id

status

No

order status.
Possible values are : CREATED | VALIDATED | PAYMENT_VALIDATED | CANCELLED | READY_FOR_SHIPMENT | SHIPPED | DELIVERED | RETURNED

skuId (applicable for admin role only)

No

id of sku related to order

Response HTTP statuses

Code

Meaning

200

Success

Response Body

Unresolved directive in <stdin> - include::snippets/order_count.json.adoc[]

1.2.3. Get a specific order

URL

/rs/orders/[id]

Method

GET

Roles allowed

admin, user

Parameters
Name Mandatory Description

order id

Yes

id of the order item to retrieve

enhanced

No

boolean flag to get enhanced order with static order configuration and catalog related items.
Possible values are : true | false

Response HTTP statuses

Code

Meaning

200

Success

401

When requested order does not belong to user

404

No result found matching given parameters

Response Body

Unresolved directive in <stdin> - include::snippets/order.json.adoc[]

1.2.4. Get fixed delivery fee configuration

URL

/rs/orders/fixeddeliveryfee

Method

GET

Roles allowed

admin

Response HTTP statuses

Code

Meaning

200

Success

Response Body

Unresolved directive in <stdin> - include::snippets/order.fixeddeliveryfee.json.adoc[]

1.2.5. Create an order

URL

/rs/orders

Method

POST

Description

Create provided order and performs operations such as validation, pricing, payment triggering …​ See user guide (TODO) for details

Roles allowed

admin, user

For user role, this order will be bound to current authenticated user.
For admin role, userLogin parameter must be provided to bind related user to this order.

Parameters
Name Mandatory Description

order item

Yes

The order to create.

userLogin item (applicable to admin role only)

Yes

The login of a user to link to this order.

Request Body

Unresolved directive in <stdin> - include::snippets/order.in.json.adoc[]

Response HTTP statuses

Code

Meaning

200

Success

400

When provided order validation process fails or when related entities have an id defined. (Id is created during persistence and cannot be provided for entity creation).

Response Body

Unresolved directive in <stdin> - include::snippets/user.json.adoc[]

1.2.6. Modify an order

URL

/rs/users

Method

PUT

Roles allowed

admin

Parameters
Name Mandatory Description

order item

Yes

The order to modify.

Request Body

Unresolved directive in <stdin> - include::snippets/order.json.adoc[]

Response HTTP statuses

Code

Meaning

200

Success

404

Not found

Response Body

Unresolved directive in <stdin> - include::snippets/order.json.adoc[]

1.2.7. Delete an order

URL

/rs/orders/[id]

Method

DELETE

Roles allowed

admin

Parameters
Name Mandatory Description

order id

Yes

id of the order to delete

Response HTTP statuses

Code

Meaning

200

Success

1.3. Eligible order discounts resource

Manages user orders.

1.3.1. Get eligible order discounts

URL

/rs/discounts/eligible

Method

GET

Description

Returns all discounts eligible for current authenticated user’s next order.

Roles allowed

user

Parameters
Name Mandatory Description

locale

No

For sample en_GB. Can be provided get localized related presentation item (localized content) in response

Response HTTP statuses

Code

Meaning

200

Success

Response Body

Unresolved directive in <stdin> - include::snippets/Discount.list.json.adoc[]