1. User 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. User resource

Manages users.

1.2.1. Get all users

URL

/rs/users

Method

GET

Roles allowed

admin

Parameters
Name Mandatory Description

search

No

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

start

No

results start offset

size

No

results size

orderBy

No

sort criteria. Defaults to id.
Possible values are : id | login | gender | firstname | lastname | disabled | activated | newslettersSubscribed | birthDate | _ phoneNumber_ | preferredLocale | creationDate | _updateDate

isDesc

No

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

Response HTTP statuses

Code

Meaning

200

Success

Response Body

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

1.2.2. Get users count

URL

/rs/users/count

Method

GET

Roles allowed

admin

Parameters
Name Mandatory Description

search

No

Search criteria. Value should match item’s id, name or description

Response HTTP statuses

Code

Meaning

200

Success

Response Body

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

1.2.3. Get a specific user

URL

/rs/users/[id]

Method

GET

Roles allowed

admin

Parameters
Name Mandatory Description

user id

Yes

id of the user item to retrieve

Response HTTP statuses

Code

Meaning

200

Success

404

No user found matching given parameters

Response Body

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

1.2.4. Get current authenticated user

URL

/rs/users/current

Method

GET

Roles allowed

admin

Response HTTP statuses

Code

Meaning

200

Success

404

No result found matching given parameters

Response Body

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

1.2.5. Create a user

URL

/rs/users

Method

POST

Roles allowed

ALL

Parameters
Name Mandatory Description

user item

Yes

The user to create.
Mandatory properties are : login, password, firstname, lastname

Request Body

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

Response HTTP statuses

Code

Meaning

200

Success

400

When provided user entity or related entities have an id defined. (Id is created during persistence and cannot be provided for entity creation). Also happens when user country does not belong to allowed countries list

409

When a user with same login already exists (login is unique)

Response Body

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

1.2.6. Modify a user

URL

/rs/users

Method

PUT

Roles allowed

admin, user

Parameters
Name Mandatory Description

user item

Yes

The user to modify.
Mandatory properties are : login, password, firstname, lastname

Request Body

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

Response HTTP statuses

Code

Meaning

200

Success

401

When provided user entity to modify does not match current authenticated user entity

Response Body

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

1.2.7. Delete a user

URL

/rs/users/[id]

Method

DELETE

Roles allowed

admin

Parameters
Name Mandatory Description

user id

Yes

id of the user to delete

Response HTTP statuses

Code

Meaning

200

Success

1.2.8. Activate a user

URL

/rs/users/[login]

Method

PUT

Roles allowed

ALL

Parameters
Name Mandatory Description

login

Yes

The user login, used as a key to retrieve the persisted user item to activate.

token

Yes

An activation token provided to user during creation.

Request Body

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

Response HTTP statuses

Code

Meaning

200

Success

404

When no user found matching provided login

Response Body

1.2.9. Request user password reset

URL

/rs/users/[login]/password

Method

POST

Roles allowed

ALL

Parameters
Name Mandatory Description

login

Yes

The user login, used as a key to retrieve the persisted user item to activate.

Response HTTP statuses

Code

Meaning

200

Success

404

When no user found matching provided login

1.2.10. Reset user password

URL

/rs/users/[login]/password

Method

PUT

Roles allowed

ALL

Parameters
Name Mandatory Description

login

Yes

The user login, used as a key to retrieve the persisted user item to activate.

token

Yes

A reset password token provided to user by e-mail during "Request user password" process.

new password

Yes

A new user password.

Response HTTP statuses

Code

Meaning

200

Success

401

When provided user login does not match current authenticated user login

404

When no user found matching provided login and token

1.2.11. Authenticate a user

URL

/rs/users

Method

HEAD

Roles allowed

ALL

Parameters
Name Mandatory Description

Basic realm

Yes

Standard Basic HTTP header with basic realm containing user login and password ("login:password" string Base 64 encoded)

Response HTTP statuses

Code

Meaning

200

Success

1.3. Mail template resource

Manages mail templates.

1.3.1. Get all mail templates

URL

/rs/mailtemplates

Method

GET

Roles allowed

admin

Parameters
Name Mandatory Description

name

No

Mail template name to search

start

No

results start offset

size

No

results size

orderBy

No

sort criteria. Defaults to id.
Possible values are : id | name | locale | creationDate | updateDate

isDesc

No

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

Response HTTP statuses

Code

Meaning

200

Success

Response Body

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

1.3.2. Get mail templates count

URL

/rs/mailtemplates/count

Method

GET

Roles allowed

admin

Response HTTP statuses

Code

Meaning

200

Success

Response Body

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

1.3.3. Get a specific mail template

URL

/rs/mailtemplates/[id]

Method

GET

Roles allowed

admin

Parameters
Name Mandatory Description

Mail template id

Yes

id of the mail template to retrieve

Response HTTP statuses

Code

Meaning

200

Success

404

No result found matching given parameters

Response Body

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

1.3.4. Create a mail template

URL

/rs/mailtemplates

Method

POST

Roles allowed

admin

Parameters
Name Mandatory Description

Mail template

Yes

The mail template to create.
Mandatory properties are : name, content, subject

Request Body

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

Response HTTP statuses

Code

Meaning

200

Success

409

When a mailtemplate with same name and locale already exists

Response Body

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

1.3.5. Modify a mail template

URL

/rs/mailtemplates

Method

PUT

Roles allowed

admin

Parameters
Name Mandatory Description

Mail template item

Yes

The mail template to modify.
Mandatory properties are : name, content, subject

Request Body

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

Response HTTP statuses

Code

Meaning

200

Success

409

When a mailtemplate with same name and locale but another id already exists

Response Body

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

1.3.6. Delete a mail template

URL

/rs/mailtemplates/[id]

Method

DELETE

Roles allowed

admin

Parameters
Name Mandatory Description

Mail template id

Yes

id of the mail template to delete

Response HTTP statuses

Code

Meaning

200

Success