If you find errors or omissions in this document, please don’t hesitate to submit an issue or open a pull request with a fix. We also encourage you to ask questions and discuss any aspects of the project on the mailing list or in the chat room. New contributors are always welcome!
Release notes

10/09/2019, v1, initial release

1. Introduction

The Big Picture

The api gateway is a place where European Reliance’s API’s of web services as APIs are exposed together with a portal help site for developers.

What are the web services APIs?

Behind the gateway, exposed, are our enterprise insurance services, which can be used by external developers, for applications that produce and consume insurance data, consumed by external parties.

Namely, it is:

parties-api

Service for parties information.

2. API gateway

In front of all the services there is a common layer called gateway. It is enforcing constraints common to all services like security, accounting and rate limiting.

Gateway is responsible for:

  • The first level of authentication and authorization of every call to the internal services

  • Counting the invocations and rate limiting them.

It is essentially the gateway guard that every call must show its credentials in order to pass.

Each API call passes from two levels of authentication and authorization.

2.1. Authentication and authorization

Levels of authentication and authorization

  • First level: each call is being checked to see two things. if it contains an API key that is authorized to access the specified API resource and if it obeys some specified rate limiting access rules. If it doesn’t then a specific gateway error response is returned (see General Web Service Errors and Web Service Rate Limits).

  • Second level: Depending on the service, each call is checked if it contains an Authorization header with a valid Bearer token.

An authorization token is fetched first from a specific service endpoint.
Steps

If a company user wants to use an externally provided program (your program) he must first authorize it to impersonate him by following a specific procedure through our company’s portal.

Within that procedure the user publishes a user-key, a 40 character key, that ties his identity with the identity of your program. This bond can be enabled, disabled, deleted, and recreated by the user whenever he wants.

The user is instructed to deliver this user-key to your program in order for you to use it for the purpose of obtaining an authorization token from the API.

This authorization token together with your api-key must be supplied as header parameters with any API call.

2.1.1. First check

At first, you must obtain an API key that uniquely identifies you, by following the procedure of signing up. After approval you will be given access to certain provided APIs.

2.1.2. Second check

The second level of authorization is the API specific authorization. Each call is checked to see if it contains an authorization header. If not then a 401 Unauthorized error response is returned.

The authorization header is an “Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxx” where the xxxx part is the token and is obtained by accessing a specific “tokens” address (see later). Steps

Please take care of your api-key, the client user-key and the resulting authorization tokens are to be stored safely and never be shared with third parties.

Use always secure communication protocols

Our services are served under HTTPS only. If you believe that your api-key or any other key or token got leaked to the outside world contact us immediately. We will disable them and supply you with new one.

If we don’t disable them, they may be used in an illegal way by a third party without us having a way to differentiate a valid usage from an invalid one. If you want your api-key to be tied permanently with your IP for added security, contact us.

2.2. API Key Usage

How to use your API key after signing up.

After signing up, you’ll be given your own, unique API key which is a 40 character string. The key:

  • Uniquely identifies you.

  • Gives you access to europisti.gr’s Web services.

  • Should be kept private and should not be shared.

The API may be used several ways. In order of precedence:

HTTP Header, the preferred way

Pass the API key into the X-api-key header:

curl -H 'X-api-key: DEMO_KEY' "https://gateway.europisti.gr/dev/parties-api/resources/parameters"
GET Request Query Param

To use your key, simply pass the key as a URL query parameter when making Web service requests. For example:

curl https://gateway.europisti.gr/dev/parties-api/resources/?api_key=YOUR_KEY"

Regardless of the HTTP method being called, the API key can always be passed as a GET parameter in the URL query. So even if you are POSTing or PUTing to a specific service, the api_key query parameter can be supplied in the URL query parameters.

Alternative Method

Depending on your usage, it can sometimes be easier to pass the API key along as HTTP Basic authentication. If you want to use this method, pass your API key in as the username, while leaving the password blank. For example:

curl "http://YOUR_KEY_HERE@gateway.europisti.gr/dev/parties-api/resources"

2.3. Web Service Rate Limits

Daily and hourly rate limits on accessing europisti.gr’s Web services.

Rate Limits

There is a limit on the number of europisti.gr web service requests you can make using your API key. Rate limits may vary by service, but the defaults are:

Hourly Limit: 1,000 requests per hour

For each API key, these limits are applied across all europisti.gr web services requests. Exceeding these limits will lead to your API key being temporarily blocked from making further requests. Depending on the limit exceeded, the block will be lifted automatically by waiting until the next hour or calendar day.

2.3.1. How Do I See My Current Usage?

Your can check your current rate limit and usage details by inspecting the X-RateLimit-Limit and X-RateLimit-Remaining HTTP headers that are returned on every API response. For example, if an API has the default hourly limit of 1,000 request, after making 2 requests, you will receive these HTTP headers in the response of the second request:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998

2.3.2. Understanding Rate Limit Time Periods

Hourly Limit

The hourly counters for your API key reset on a rolling basis. Example:

  1. If you made 500 requests at 10:15AM and 500 requests at 10:25AM, your API key would become temporarily blocked.

  2. This temporary block of your API key would cease at 11:15AM, at which point you could make 500 requests.

  3. At 11:25AM, you could then make another 500 requests.

2.3.3. Rate Limit Error Response

If your API key exceeds the rate limits, you will receive a response with an HTTP status code of 429 (Too Many Requests).

2.3.4. Need Higher Limits?

If you’re building an application that needs higher rate limits, we’d be happy to work with you. Contact us for more details.

2.3.5. Errors at gateway’s level

Certain, general errors will be returned in a standardized way from all web services. Additional, service-specific error messages may also be returned (see individual service documentation for those details). The following list describes the general errors any application may return:

Error Codes
Error Code HTTP Status Code Description

API_KEY_MISSING

403

An API key was not supplied. Read API key usage for details on how to pass your API key to the API.

API_KEY_INVALID

403

An invalid API key was supplied. Double check that the API key being passed in is valid, or sign up for an API key.

API_KEY_DISABLED

403

The API key supplied has been disabled by an administrator. Please contact us for assistance.

API_KEY_UNAUTHORIZED

403

The API key supplied is not authorized to access the given service. Please contact us for assistance.

API_KEY_UNVERIFIED

403

The API key supplied has not been verified yet. Please check your e-mail to verify the API key. Please contact us for assistance if needed.

HTTPS_REQUIRED

400

Requests to this API must be made over HTTPS. Ensure that the URL being used is over HTTPS.

OVER_RATE_LIMIT

429

The API key has exceeded the rate limits. Read rate limits for more details or contact us for assistance.

NOT_FOUND

404

An API could not be found at the given URL. Check your URL.
Error Response Body

The error response body will contain an error code value from the table above and a brief description of the error. The descriptions are subject to change, so it’s suggested that any error handling must use the HTTP status code or the error code value for error handling (and not the content of the message description).

Error Message Response Formats

Depending on the detected format of the request, the error message response may be returned in JSON, XML, CSV, or HTML. Requests of an unknown format will return errors in JSON format.

JSON Example

{
 "error": {
   "code": "API_KEY_MISSING",
   "message": "No api_key was supplied. Get one at https://gateway.europisti.gr"
  }
}

XML Example

<response>
  <error>
    <code>API_KEY_MISSING</code>
    <message>No api_key was supplied. Get one at https://gateway.europisti.gr</message>
  </error>
</response>

CSV Example

Error Code,Error Message
API_KEY_MISSING,No api_key was supplied. Get one at https://gateway.europisti.gr

HTML Example

<html>
  <body>
    <h1>API_KEY_MISSING</h1>
    <p>No api_key was supplied. Get one at {uri-mtr-gw}</p>
  </body>
</html>

2.4. Dev vs Prod

In order to access a developer’s sandbox for developing and testing reasons, it is enough just to add the word dev in the path after the server name and before the actual api’s path, for example:

Production URI        https://gateway.europisti.gr/parties-api/resources
Sandbox URI           https://gateway.europisti.gr/dev/parties-api/resources

Of course it is necessary for your API key to be accepted and given access to both environments by the authorization procedures that are established with your registration.

By having a valid and authorized X-api-key, any call can pass gateway’s checks and access any internal APIs that was given access to it. One such API is the mtr-api.

3. PARTIES-API intro

General information

The parties-api is accessible via https://gateway.europisti.gr/dev/parties-api/resources. In order to use this API, you must pass:

  • Your API key via one of the supported methods, preferably as header parameter

  • AND an authorization token via the Authorization header.

To make requests to the API two headers are required:

X-Api-Key:     YOUR_API_KEY_HERE
Authorization: Bearer CLIENT_BEARER_TOKEN_HERE

Without these two headers all calls to mtr-api will be rejected with the response 401-Unauthorized

3.1. Authorization

3.1.1. Getting authorization tokens

An Authorization client bearer token is thus required, and the way to get it is by using MTR_API token service.

A convenience header X-Token-Expires-In: xxxx seconds is returned by default in every request. It is the time remaining in seconds after which the token will be valid. With this header it is possible to calculate beforehand when a token renewal call will be needed.

By default the token is valid for 30 minutes after which the server will reject subsequent calls with the response 401 Unauthorized and an extra error header X-Error: Token Expired

If the client receives this error he can request a new token which will be valid for 30 more minutes.

No extra header
If the client gets response 401 Unauthorized without the extra header, then that means the authentication failed on the server side due to either wrong keys or because the client of the user-key refuses access to the X-Api-Key holder. In such case it is advised to first get in contact with your client (of user-key) to remedy the situation.
string ISO date

When the specification of a date named field is “string ISO date”, it is expected to be supplied with a date in ISO 8601 format like “2018-10-28” or a datetime like “2018-10-28T13:55:00”.

The date fields are expected to be in the Greek time zone and the conversions are handled by the api. When a datetime field is returned and it doesn’t end with a 'Z' (which denotes a UTC date) then it is supposed to be a Greek LocalDate value.

3.2. Errors

When the parties-api encounters an error condition outside the normal flow, it tries to return that error condition with a specific header named X-Error. So when it encounters incomplete or bad requests, incoming data validation errors or specific internal error conditions, it sets the error header informing the client application with a more specific message.

You will use this information for correcting the condition and maybe retrying the operation. For example when the authentication token expires, the client application receives a 401 Unauthorized status with the specific header X-Error: Token Expired signalling that a new token must be obtained first from the “tokens” resource and then the operation can be retried.

3.2.1. Other headers

When an operation returns with a failure status, it is possible that a header named X-Error is returned and usually an error entity with error details for both.

For operations like POSTing new entities and for the success status 201 Created, a Location header is set, according to standards with the uri of the new entity.

Some operations return extra information or actions in the Link headers. For example when issuing an application a link for the notification document is included. The operations that return this kind of information are documented.

For reference purposes, click this link to find out more about known response status codes.

3.3. CORS

The parties-api supports CORS and set required headers.

4. Parties

Overview

The following API endpoints can be used to programmatically create and retrieve parties.

Available actions are:

Search for parties

Returns a list of parties for the search criteria. Can be paged if start and limit request parameters is used.

Retrieve a party

Retrieve a party.

Insert new party

Create a new party.

Guides

The api informs you for any payload validation errors or other type of errors with an error status and an entity.

4.1. Search for

In order to search for user’s parties a GET request must be submitted to the resource. The response is a JSON array of search result parties.

Resource URL

GET https://gateway.europisti.gr/dev/parties-api/resources/parties

Resource Information

Response formats

JSON

Requires authentication?

Yes (user context)

Rate limited?

Yes
Parameters
Name Required Description Default Size Example

start

optional

starting row number, used for paging

1

1

limit

optional

result page size, max rows, used for paging

20

5000

20

policyId

optional

policy’s or application’s unique id

10

1234567890
Example Request
curl -H 'X-Api-Key: your_api_key' \
-H 'Authorization: Bearer user_token' \
"https://gateway.europisti.gr/dev/parties-api/resources/parties?start=1&size=100&policyId=123456789"
Example Response
[
    {
        "afm": "1234567890",
        "birthdate": "1992-06-13",
        "fathersName": "ΒΑΣΙΛΕΙΟΣ",
        "firstName": "ΚΩΝΣΤΑΝΤΙΝΟΣ",
        "gender": "1",
        "lastName": "ΠΑΠΑΔΟΠΟΥΛΟΣ",
        "occupationCode": "019",
        "partyAddresses": [
            {
                "addressId": 5214685,
                "addressType": "ΜΟΝΙΜΗ ΚΑΤΟΙΚΙΑ",
                "city": "ΟΡΕΣΤΙΑΔΑ",
                "inUse": "1",
                "line_1": "ΚΑΛΛΙΠΟΛΕΩΣ 45",
                "postCode": "68200"
            },
            {
                "addressId": 4883718,
                "addressType": "ΜΟΝΙΜΗ ΚΑΤΟΙΚΙΑ",
                "city": "ΤΡΙΠΟΛΗ",
                "inUse": "0",
                "line_1": "ΛΕΟΝΤΟΣ 32",
                "postCode": "22100"
            }
        ],
        "partyContacts": [
            {
                "contact": "2552401234",
                "contactId": 2548781,
                "contactType": "ΟΙΚΙΑΣ",
                "inUse": "1",
                "preferred": "1"
            },
            {
                "contact": "6983678912",
                "contactId": 1891322,
                "contactType": "ΚΙΝΗΤΟ",
                "inUse": "1",
                "preferred": "1"
            }
        ],
        "partyId": 441725210,
        "personType": "01"
    },
    ...
]

4.2. Retrieve one

In order to return a party when the party id is known, a GET request must be submitted to the resource followed by the party id. In case the party exists and the user has the rights to display it, it will return a success 200 Success response status with entity details or a 400 Bad request response status with an error entity describing the error condition.

Resource URL

GET https://gateway.europisti.gr/dev/parties-api/resources/parties/:id

Resource Information

Response formats

JSON

Requires authentication?

Yes (user context)

Rate limited?

Yes
Example Request
curl -H 'X-Api-Key: your_api_key' \
-H 'Authorization: Bearer user_token' \
-X GET "https://gateway.europisti.gr/dev/parties-api/resources/parties/123456789"
Example Error Response

A typical error entity is:

{
 "status": "ERROR",
 "error": "-1",
 "message": "ΔΕΝ ΕΧΕΤΕ ΠΡΟΣΒΑΣΗ ΣΤΗΝ ΑΙΤΗΣΗ"
}
Example Success Response
{
    "afm": "1234567890",
    "birthdate": "1992-06-13",
    "fathersName": "ΒΑΣΙΛΕΙΟΣ",
    "firstName": "ΚΩΝΣΤΑΝΤΙΝΟΣ",
    "gender": "1",
    "lastName": "ΠΑΠΑΔΟΠΟΥΛΟΣ",
    "occupationCode": "019",
    "partyAddresses": [
        {
            "addressId": 5214685,
            "addressType": "ΜΟΝΙΜΗ ΚΑΤΟΙΚΙΑ",
            "city": "ΟΡΕΣΤΙΑΔΑ",
            "inUse": "1",
            "line_1": "ΚΑΛΛΙΠΟΛΕΩΣ 45",
            "postCode": "68200"
        },
        {
            "addressId": 4883718,
            "addressType": "ΜΟΝΙΜΗ ΚΑΤΟΙΚΙΑ",
            "city": "ΤΡΙΠΟΛΗ",
            "inUse": "0",
            "line_1": "ΛΕΟΝΤΟΣ 32",
            "postCode": "22100"
        }
    ],
    "partyContacts": [
        {
            "contact": "2552401234",
            "contactId": 2548781,
            "contactType": "ΟΙΚΙΑΣ",
            "inUse": "1",
            "preferred": "1"
        },
        {
            "contact": "6983678912",
            "contactId": 1891322,
            "contactType": "ΚΙΝΗΤΟ",
            "inUse": "1",
            "preferred": "1"
        }
    ],
    "partyId": 441725210,
    "personType": "01"
}

4.3. Insert

Fields afm, firstName, lastName and birthday are mandatory. The service will check if it already exists and update it or insert a new one. On success returns the partyId.

The field birthdate must contain the desired date, formatted as "yyyy-MM-dd" for example "2019-02-15"
Resource URL

POST https://gateway.europisti.gr/dev/parties-api/resources/parties

Resource Information

Response formats

JSON

Requires authentication?

Yes (user context)

Rate limited?

Yes
Example Request
curl -H 'X-Api-Key: your_api_key' \
-H 'Authorization: Bearer user_token' \
-H 'Content-type: application/json' \
-X POST "https://gateway.europisti.gr/dev/parties-api/resources/parties"
-d '{
    "afm": "1234567890",
    "birthdate": "1992-06-13",
    "fathersName": "ΒΑΣΙΛΕΙΟΣ",
    "firstName": "ΚΩΝΣΤΑΝΤΙΝΟΣ",
    ...
}'
Example Error Response
{
 "status": "ERROR",
 "error": "-2",
 "message": "...."
}
Example Success Response
{
  "partyId": 441725210
}