API docs by Redocly

Gatekeeper (3.9.0)

Download OpenAPI specification:

E-mail: support@easterngraphics.com

This web service regulates the access to the EAIWS Cloud.

Things to be aware of

Access to the API described here is distributed by a load balancer to the servers running in the background.

However, it can happen that within a short time window after the failure of a server, the requests are still sent to the failed server. To avoid this problem, we recommend resending the request in the event of a time out, slow response or a response with the status code 504.

The following URL should be used as the base url for all API endpoints described here: https://gatekeeper.eaiws.pcon-solutions.com/v3

Session

Almost all EAIWS operations require a valid session. In order to generate these, various information about the underlying data must be provided.
The following functions simplify this process.
In addition, tasks such as load balancing or fallback policies for failing EAIWS servers are supported without additional effort on the client side.

The only requirement for these operations is a valid customer id.
Please contact your person in charge to get one.

Opening a session

The most important property of a session is its link to the OFML data. There are the following possibilities:

One data set used for all end users

In this case, all end users are working with the same data set. Therefore, it is not necessary for the end user to log in via pCon.login. Instead, a long-lived refresh token is generated during the registration of the gatekeeper id. This token will then be used to query the data.

Warning: In case the data is not publicly accessible via a website or similar, the application should authorize itself via pCon.login and transmit the pCon.login access token as applicationToken to the gatekeeper.

Dynamic data set defined by the pCon.update subscriptions of the individual end user

In this case, the end user must first authorize himself via pCon.login. The access token generated in this process must then be provided to the gatekeeper using the userToken parameter. The gatekeeper then queries the data assigned to the user from pCon.update and creates a session that is individually tailored to the user.

path Parameters
id
required
string

The gatekeeper id identifies a product, in special cases also a specific configuration of a product. The id is unique and will be communicated to you at the time of order.

header Parameters
X-pCon-Services
string

This header allows you to overwrite the services used in the background. It is used exclusively for test purposes.

Request Body schema: application/json

Optional arguments to influence the creation of the EAIWS session.

locale
string

This value is used to set the locale of the EAIWS session. The value of the locale parameter consists of an ISO 639 alpha-2 language code and an ISO 3166-1 alpha-2 country code, separated by an underscore (_). The country code may be followed by a commercial at (@) and a variant code.

This value is also used to set the defaultEncoding if no value is explicitly set in the request body. For that purpose the following mapping is used:

locale defaultEncoding
bg_* windows-1251
cs_* windows-1250
el_* windows-1253
et_* windows-1257
fi_* windows-1252
ga_* windows-1252
hr_* windows-1250
hu_* windows-1250
ja_* windows-932
ko_* windows-949
lt_* windows-1257
lv_* windows-1257
mk_* windows-1251
pl_* windows-1250
ro_* windows-1250
ru_* windows-1251
sk_* windows-1250
sl_* windows-1250
sq_* windows-1250
sr_* windows-1250
tr_* windows-1254
uk_* windows-1251
vi_* windows-1258
zh_* windows-950

Note: Values other than those listed in the mapping are allowed and in some cases necessary. Furthermore, the mapping can be extended at any time.

Further information can be found in the EAIWS specification.

defaultEncoding
string (ISO/IEC 8859)

This setting can be used to override the character encoding used while processing the OFML data.

Warning: This value should only be set in rare cases, since an incorrect value can cause errors in the processing of OFML data. In most cases the value for locale should be set instead.

userToken
string

The pCon.login access token which is associated with the end user.

applicationToken
string

The pCon.login access token which is associated with the application.

applicationId
string

In some cases it may be useful to apply for an additional application id in addition to the actual gatekeeper id. This application id is used to uniquely identify the application accessing the gatekeeper id.

Note: This should always be done if a certain application can be operated with several different gatekeeper ids and especially if the ids that are used can be controlled by the user.

gatekeeperSessionSettings
object

This value is used for optimization while assigning the end user to an EAIWS server. When a session is successfully opened, in some (not all) cases the response contains a property with this exact name. The returned value can then be used for another request.

Important: the return value must not be shared between different end users or applications. Furthermore, it should only be stored within one browser session. (When the browser is closed, the value should be deleted.)

Responses

Response Schema: application/json
server
required
string

The url of the server on which the session was created.

sessionId
required
string

The id of the session which was created.

keepAliveInterval
required
integer

The interval in seconds after a keepAlive request to the EAIWS server is necessary to maintain the session.

gatekeeperSessionSettings
object (optional)

This field is returned in some (not all) cases. The client can include it in any further request from the same end user using the same browser session and the same gatekeeper id.

Important: the value must not be changed. It should also not be stored longer than the browser session.

A reasonable use of this feature would be a browser based application where each tab uses its own EAIWS session. This value ensures that all tabs use the same EAIWS server and thus some resources from the browser cache can be reused.

Each error is answered with a response in the following scheme.

A list of all errors can be found in the Errors section.

Response Schema: application/json
required
object

This object is designed to easily identify any errors that may occur so that they can be handled accordingly by the client application.

id
required
string

A unique id that describes the error very precisely.

type
required
string

A general categorization of the error.

code
required
string

The value corresponds to the http status code which is used.

Important: this value is not unique. To distinguish one error from another the id must be used.

scopes
Array of strings

A list of labels that give clues to the origin of the problem.

message
string

The error message of the occurred error.

Important: the error messages are rather addressed to developers or even come from a different web service. They are therefore not suitable as error messages for the end user.

Request samples

Content type
application/json
{
  • "locale": "string",
  • "defaultEncoding": "string",
  • "userToken": "string",
  • "applicationToken": "string",
  • "applicationId": "string",
  • "gatekeeperSessionSettings": { }
}

Response samples

Content type
application/json
{
  • "server": "string",
  • "sessionId": "string",
  • "keepAliveInterval": 0,
  • "gatekeeperSessionSettings": { }
}

Settings

Some products are quite customizable and different properties of them can be controlled by configuration options. This API allows you to query configuration settings stored for a given product and thus adapt the respective product and its behavior accordingly.

Request one product configuration

This API can be used to request the product configuration.

path Parameters
productId
required
string

The id assigned to the product.

settingsId
required
string

The id of the product settings.

header Parameters
X-pCon-Services
string

This header allows you to overwrite the services used in the background. It is used exclusively for test purposes.

Responses

Response Schema: application/json
property name*
additional property
any

Each error is answered with a response in the following scheme.

A list of all errors can be found in the Errors section.

Response Schema: application/json
required
object

This object is designed to easily identify any errors that may occur so that they can be handled accordingly by the client application.

id
required
string

A unique id that describes the error very precisely.

type
required
string

A general categorization of the error.

code
required
string

The value corresponds to the http status code which is used.

Important: this value is not unique. To distinguish one error from another the id must be used.

scopes
Array of strings

A list of labels that give clues to the origin of the problem.

message
string

The error message of the occurred error.

Important: the error messages are rather addressed to developers or even come from a different web service. They are therefore not suitable as error messages for the end user.

Response samples

Content type
application/json
{
  • "advice": [
    ]
}

Request multiple product configurations

In rare cases, a product may need to query several different configuration settings. In this case the search operation can be used.

header Parameters
X-pCon-Services
string

This header allows you to overwrite the services used in the background. It is used exclusively for test purposes.

Request Body schema: application/json
required

A search request always refers to one product, but several setting ids can be specified.

productId
required
string

The id assigned to the product.

settingsId
required
Array of strings

A list of product setting ids.

Responses

Response Schema: application/json
required
object

An object that contains the search results. The key of the object corresponds to the settings id and the value to the actual settings.

property name*
additional property
object

Any information depending on the specified product.

required
object

An object that contains information about errors that occurred during the processing of the request. The key of the object corresponds to the settings id and the value to the information about the errors that occurred. The structure of the errors is the same as the error property of the error response of the API.

A list of all errors can be found in the Errors section.

additional property
object (error)

This object is designed to easily identify any errors that may occur so that they can be handled accordingly by the client application.

id
required
string

A unique id that describes the error very precisely.

type
required
string

A general categorization of the error.

code
required
string

The value corresponds to the http status code which is used.

Important: this value is not unique. To distinguish one error from another the id must be used.

scopes
Array of strings

A list of labels that give clues to the origin of the problem.

message
string

The error message of the occurred error.

Important: the error messages are rather addressed to developers or even come from a different web service. They are therefore not suitable as error messages for the end user.

Each error is answered with a response in the following scheme.

A list of all errors can be found in the Errors section.

Response Schema: application/json
required
object

This object is designed to easily identify any errors that may occur so that they can be handled accordingly by the client application.

id
required
string

A unique id that describes the error very precisely.

type
required
string

A general categorization of the error.

code
required
string

The value corresponds to the http status code which is used.

Important: this value is not unique. To distinguish one error from another the id must be used.

scopes
Array of strings

A list of labels that give clues to the origin of the problem.

message
string

The error message of the occurred error.

Important: the error messages are rather addressed to developers or even come from a different web service. They are therefore not suitable as error messages for the end user.

Request samples

Content type
application/json
{
  • "productId": "example-product-id",
  • "settingsId": [
    ]
}

Response samples

Content type
application/json
{
  • "results": {
    },
  • "errors": {
    }
}

Crawler

Note: The crawler API is not available for every gatekeeper id. An additional contract must be signed for its use.

With this API it is possible to perform certain tasks over all or part of the OFML data assigned to the gatekeeper id.

Possible tasks include for example:

  • exporting a list of items with their texts and prices
  • creating and exporting article images

How it works

The first step is to define the data to be made available in the export file. This must be done during the request for API access with the responsible contact person. Once this has been done and the gatekeeper id has been enabled for the crawling API, the crawling progress can be started via the specified API.

The crawling itself runs asynchronously and lasts from a few seconds to several hours, depending on the size of the data set. The result is a SQLite database with the previously defined information.

Note: We use a SQLite database as an exchange format because of its simple and clear structure. Furthermore, it allows us to store all necessary data (even binary data like images) within a single file. Since the use of a SQLite database is very easy with almost any programming language, the customer also saves the implementation of a new and non standardized export format.

The exact structure of the database may vary from customer to customer. A corresponding documentation will be provided after the request of the API access.

Start the crawling process

This request starts the crawling process. In case of success a job id is delivered as a response.
However, the actual processing of the job can take from a few seconds to several hours.

The status and the final result can be requested using the other API endpoints.

path Parameters
id
required
string

The gatekeeper id identifies a product, in special cases also a specific configuration of a product. The id is unique and will be communicated to you at the time of order.

header Parameters
X-pCon-Services
string

This header allows you to overwrite the services used in the background. It is used exclusively for test purposes.

Request Body schema: application/json
required

The request body describes the crawling job in additional detail.

object

The same options that are used when opening the session can be specified here.

locale
string

This value is used to set the locale of the EAIWS session. The value of the locale parameter consists of an ISO 639 alpha-2 language code and an ISO 3166-1 alpha-2 country code, separated by an underscore (_). The country code may be followed by a commercial at (@) and a variant code.

This value is also used to set the defaultEncoding if no value is explicitly set in the request body. For that purpose the following mapping is used:

locale defaultEncoding
bg_* windows-1251
cs_* windows-1250
el_* windows-1253
et_* windows-1257
fi_* windows-1252
ga_* windows-1252
hr_* windows-1250
hu_* windows-1250
ja_* windows-932
ko_* windows-949
lt_* windows-1257
lv_* windows-1257
mk_* windows-1251
pl_* windows-1250
ro_* windows-1250
ru_* windows-1251
sk_* windows-1250
sl_* windows-1250
sq_* windows-1250
sr_* windows-1250
tr_* windows-1254
uk_* windows-1251
vi_* windows-1258
zh_* windows-950

Note: Values other than those listed in the mapping are allowed and in some cases necessary. Furthermore, the mapping can be extended at any time.

Further information can be found in the EAIWS specification.

defaultEncoding
string (ISO/IEC 8859)

This setting can be used to override the character encoding used while processing the OFML data.

Warning: This value should only be set in rare cases, since an incorrect value can cause errors in the processing of OFML data. In most cases the value for locale should be set instead.

userToken
string

The pCon.login access token which is associated with the end user.

applicationToken
string

The pCon.login access token which is associated with the application.

applicationId
string

In some cases it may be useful to apply for an additional application id in addition to the actual gatekeeper id. This application id is used to uniquely identify the application accessing the gatekeeper id.

Note: This should always be done if a certain application can be operated with several different gatekeeper ids and especially if the ids that are used can be controlled by the user.

object

Most of the options supported by the crawler plugin can be set via this property.

Important: some settings are, however, blocked. These include the following:

  • accessToken
  • clientId
  • openSessionArguments
  • refreshToken
  • workerConfig

Furthermore, the data transmitted via pluginOptions may be validated against a JSON schema which may be dependent on the gatekeeper id and impose additional restrictions.

The options must be defined exactly as they are specified in the crawler plugin documentation. (However, within the pluginOptions properties.)

property name*
additional property
any

Responses

Response Schema: application/json
jobId
required
string
Deprecated

The unique id assigned to a crawling job by the gatekeeper.

Note: this value must always be used when the request is sent to and crawling related gatekeeper API.

server
required
string

The url of the server on which the session was created.

crawlingId
required
string

The unique id assigned to a crawling job by the EAIWS crawling plugin.

Note: this value must always be used when the request is sent to the EAIWS crawling plugin directly.

Response Schema: application/json
required
object

This object is designed to easily identify any errors that may occur so that they can be handled accordingly by the client application.

id
required
string

A unique id that describes the error very precisely.

type
required
string

A general categorization of the error.

code
required
string

The value corresponds to the http status code which is used.

Important: this value is not unique. To distinguish one error from another the id must be used.

scopes
Array of strings

A list of labels that give clues to the origin of the problem.

message
string

The error message of the occurred error.

Important: the error messages are rather addressed to developers or even come from a different web service. They are therefore not suitable as error messages for the end user.

object

Additional information about the error if the error is related to an external HTTP request.

status
integer

The HTTP status code of the external request that caused the error.

statusText
string

The HTTP status text of the external request that caused the error.

Request samples

Content type
application/json
{
  • "sessionOptions": {
    },
  • "pluginOptions": {
    }
}

Response samples

Content type
application/json
{
  • "jobId": "string",
  • "server": "string",
  • "crawlingId": "string"
}

Requesting the crawling status Deprecated

Deprecated: This endpoint is deprecated and will be removed in future versions. Please use the API of the Crawler plugin directly.

This API can be used to query the status of the crawling process.

If the crawling was completed successfully, the response includes a download link for the created database.

Note: both the status information and the generated database can only be retrieved up to 1 day after the crawling process has finished. After that, they are automatically deleted from the corresponding server.

path Parameters
jobId
required
string

The unique id assigned to a crawling job by the gatekeeper.

Note: this value must always be used when the request is sent to and crawling related gatekeeper API.

header Parameters
X-pCon-Services
string

This header allows you to overwrite the services used in the background. It is used exclusively for test purposes.

Responses

Response Schema: application/json
finished
required
boolean

Determines if the crawling process was finished.

downloadUrl
string

In case the crawling process was completed successfully, this field specifies a URL for downloading the database.

Each error is answered with a response in the following scheme.

A list of all errors can be found in the Errors section.

Response Schema: application/json
required
object

This object is designed to easily identify any errors that may occur so that they can be handled accordingly by the client application.

id
required
string

A unique id that describes the error very precisely.

type
required
string

A general categorization of the error.

code
required
string

The value corresponds to the http status code which is used.

Important: this value is not unique. To distinguish one error from another the id must be used.

scopes
Array of strings

A list of labels that give clues to the origin of the problem.

message
string

The error message of the occurred error.

Important: the error messages are rather addressed to developers or even come from a different web service. They are therefore not suitable as error messages for the end user.

Response samples

Content type
application/json
{
  • "finished": true,
  • "downloadUrl": "string"
}

Errors

To make the handling of possible errors as easy as possible, each error response has both a unique id for the exact handling of a specific error and a categorized type for the handling of a group of errors.

There are the following errors

Id Type Code Description
api-pcon-update-too-many-update-channels api 409 The user has too many data channels. This problem can only be solved by changing the settings in pCon.update.
api-unknown api 409 An unexpected error occurred while communicating with a web service required for the processing of the request.
authorization-application authorization 401 The authorization of the application is invalid or expired.
authorization-user authorization 401 The authorization of the user is invalid or expired.
internal-invalid-configuration internal 500 The configuration of this gatekeeper id is invalid.
internal-unknown internal 500 An unexpected error has occurred.
license-invalid-feature-property license 401 A license is granted, but the value of feature property doses not match the required value.
license-invalid-license-assignment license 401 The license assignment on the part of pCon.update is incorrect. This error can only be fixed in the settings of pCon.update.
license-license-already-issued-for-user license 401 The license has already been occupied by this user.
license-license-exhausted license 401 The license was used too often. Used licenses must first be released and the request can then be repeated.
license-missing-feature license 401 A license is granted, but it does not include the required license feature.
license-missing-feature-property license 401 A license is granted, but the required feature property is missing.
license-no-license license 401 The user or the application does not have the necessary license.
license-release-used-too-often license 401 The license release feature was used too often. The user has to wait some time until he can use it again. For more information see the documentation of pCon.login.
license-unknown license 401 An unexpected error related to licensing has occurred.
network-eaiws network 503 None of the EAIWS servers are currently accessible.
network-unknown network 503 An unexpected network error has occurred.
request-action-not-allowed request 403 This action is not allowed.
request-application-not-allowed request 403 The application is not allowed to perform the requested operation.
request-bad-request request 400 The request did not match the specifications and the processing was therefore rejected.
request-method-not-allowed request 405 This error is always returned if the request method does not match the one from the specification.
request-not-found request 404 The specified gatekeeper id or configuration could not be found.
request-tag-not-allowed request 403 The use of this pool via tag is not allowed.

Changelog

This section only deals with the changes to version 3 (i.e. all paths beginning with /v3/) of the API. Major changes which contain breaking changes are always provided separately as a new API endpoint.

However, minor changes that are downward compatible and bug fixes are provided directly and without further notification. The following overview can therefore be used to keep up to date with new features.

Note: there may be versions without changes recorded in the changelog. In such a case, the changes in the new version have been limited to other (non-public) API endpoints or internal data structures.

3.9.0

There were no changes to the API described in this documentation.

3.8.0

There were no changes to the API described in this documentation.

3.7.0

API enhancements

  • if the start of the crawling fails due to an error caused by the processing of the crawling plugin, additional information about the status code and the error message is now passed on to the client via the info property in the error response.

3.6.0

There were no changes to the API described in this documentation.

3.5.0

API enhancements

  • if the opening of the session fails due to a soap error, then its error message is now also used for the error message sent to the client

3.4.0

There were no changes to the API described in this documentation.

3.3.0

API enhancements

  • supported for the X-pCon-Services header was added
  • the crawlingId was added to the /v3/crawler/start/ response

3.2.0

API enhancements

  • bad gateway responses from the EAIWS server are now marked as network-eaiws error
  • invalid EAIWS responses are now marked as api-unknown error
  • the startCrawling API now returns the URL of the EAIWS server
  • it is now possible to pass pluginOptions to the startCrawling API
  • the mapping between locale and defaultEncoding has been extended by the following languages
    • Greek
    • Estonian
    • Croatian
    • Japanese
    • Korean
    • Lithuanian
    • Macedonian
    • Slovenian
    • Albanian
    • Serbian
    • Ukrainian
    • Vietnamese
    • Chinese

3.1.0

Feature summary

  • If the pCon.login based licensing is activated, it is now possible to check the existing license features in addition to the actual license.

API enhancements

  • the following new errors have been added

    • license-invalid-feature-property
    • license-missing-feature
    • license-missing-feature-property

  • the mapping between locale and defaultEncoding has been extended by the following languages

    • Bulgarian
    • Latvian
    • Slovak

3.0.1

API enhancements

  • the mapping between locale and defaultEncoding has been extended by the following languages
    • Hungarian
    • Romanian
    • Czech