Elcome Micro Services API¶

Please note that this API is intended for real-time access and not to batch build an eCat. If you need to batch build an eCat, please contact your Elcome representative for alternative options.

Introduction¶

To provide modern real-time data delivery of catalogue data (Xchecker data) to our clients, a new RESTful API layer has been developed called Elcome Micro Services (EMS). It builds upon an existing base API layer (IDL Micro Services) and utilises the latest industry standard technologies and principles. Its main purpose is to allow access to the Xchecker data (via the IDL) in a manner suitable for real-time eCats or Product Finder type applications. This open access philosophy is a key part of the Elcome strategy to allow you, our clients, secure access to your data in a form suitable to you and your customers.

Data Source¶

On a nightly schedule, Xchecker data is loaded into the corresponding Intermediate Data Layer and optionally a search database, which is where it then becomes available to this API. Within Xchecker, there is control over which products can get to the IDL and which can be displayed by various consumers (eCat etc).

Advanced Search Data Source¶

The advanced search option uses a separate non-sql datastore and allows for much faster and more flexible searches across a range of product and vehicle fields including word root and synonym features. To enable this functionality please contact you Elcome representative.

Services Architecture¶

The EMS API layer is divided into sections according to logical use and to allow for future smart deployment strategies (e.g. Docker).

The IDL database is a Microsoft SQL database that is a read-only, fast, more easily readable transform of the Xchecker data. Access to the IDL data is only via the Elcome IDL Microservices (EIMS) that optimises data retrieval and performance and removes any complexity of the underlying database structure.

The Elcome Micro Services (EMS) is a further API layer (RESTful) optimised for simplified data retrieval by consumer systems. It is this layer that understands how to transform the Xchecker data specifically for use by electronic catalogues and product information systems. The IDL database, Elcome IDL Micro Services and Elcome Micro Services Intellectual Property Rights are the property of Elcome Limited.

Technology¶

The API was designed to the latest standards using Swagger 2.0 and OpenAPI 3.0. The Swagger UI is built in to the API and can be viewed on the URL assigned to you (this will be supplied by your Elcome account manager).

The Swagger interface allows you to explore the methods, their input and output models and test the calls. This can be used to understand and test the methods intended for your application and to report any issues found.

The swagger.json file from this site can be used in the Swagger editor to produce client code (stubs) in a variety of languages.

The url and authorisation details will be sent to you by your Elcome account manager. You must obtain an authorisation token (by using the 'Authorise' button) before any of the method calls will work. Please do not disclose these details to any unauthorised persons.

Hosting¶

The services are currently hosted by Elcome using our current ISP (UK Fast) where we have private dedicated servers. We chose dedicated servers so that we have full control over the usage and therefore can control the server resources in greater detail. All efforts have been made to ensure that these services are as fast and efficient as possible but due to the nature of some of them, there may be small delays if certain options are chosen. These possible slower calls will be explained in each of the affected methods in the following sections.

All services are RESTful using https protocol to ensure data transfer security and require service level specific authentication. We use IdentityServer4 for API authentication which is explained in the Security section.

For more advanced hosting requirements please contact your Elcome representative who will be happy to discuss your requirements.

Security¶

We take the security of your data seriously, so we use IdentityServer4 (IDS4) for secure token generation and API access authorisation. The generated token is then passed in the request authentication header for each call to the API you make. You will be given a client id, a shared secret, unique to you, and a scope identifier to use when requesting a token from our IdentityServer.

IdentityServer is a mature open source application which is part of the .NET Foundation which provides governance and legal backing. It is an officially certified implementation of OpenID Connect.

Implementation Details¶

We use OAuth 2.0 (OAuth 2.0 is the industry-standard protocol for authorization), using the “Client Credentials” flow.

To request an access token, POST to https://login.elcome.co.uk/connect/token with the following parameters in the body (using form encoding):

client_id=clientId&
client_secret=clientSecret&
grant_type=client_credentials&
scope=scope

where clientID, client_secret and scope will be provided by Elcome.

You will receive a json response similar to the following:

{

    "access_token": "f1yXSrb_DXForZ905M…fgNtZc1xguKMoAt2oW",
    "expires_in": 3600,
    "token_type": "Bearer"
}

When you make your webapi requests, include the access_token in the “Authorization” HTTP header using the “Bearer” authentication type, e.g.

GET /v1/somecall HTTP/1.1
Host: example.host
Authorization: Bearer f1yXSrb_DXForZ905M…fgNtZc1xguKMoAt2oW
Accept: application/json

If the access_token is missing or expired, the webapi request will return HTTP status code 401 “Unauthorized”.

CURL example¶

curl --data "client_id=clientId&client_secret=clientSecret&grant_type=client_credentials&scope=scope" https://login.elcome.co.uk/connect/token

Testing using Postman¶

The API can also be tested using Postman (https://www.getpostman.com/)

An authentication token must first be generated for Postman:

Select 'Get New Access Token' and from the following dialogue enter the details provided to you by Elcome for 'Client ID', 'Client Secret' and 'Scope'. Ensure the Grant Type is set tp 'Client Credentials' and 'Client Authentication' is set to 'Send as Basic Auth header' and the 'Access Token URL' is set as below.

Once the Token has been generated, select 'Use Token'.

Postman will then use the token for any of the selected method calls.

Licensing¶

Access to the API is via Elcome supplied details that is specified at a client url level. In other words, each application that requires access to the API will require new credentials and is classified as a new license.