Developer and Service Provider User Guide Developer and Service Provider User Guide

ECIM is a cloud platform (Infrastructure as a Service) for city mobility services. It provides web services for city mobility (on-street and off-street parking) and payment layer using account and payments service connectors.

It integrates on-street parking, off-street parking, public transport and other mobility facilities. ECIM is architecture constructed of open web services connected with external services and information sources.

Service providers can publish/register their services to the ECIM’s marketplace. Then a developer can create an application that calls these services. The application will also make use of the user management system and the payment system of the platform.

 

Developers can consume the ECIM API and create mobility applications based on a number of services which are available via a unified, common way through the API.

As a developer you have to first register and then login to the ECIM platform. Once logged-in you can Browse Marketplace and choose the service you want to subscribe to and click on button "Subscribe" in the details section. To manage your subscriptions visit My Subscriptions at the top of the page of ECIM platform.

As a Developer you can subscribe to an available service/data through the service details screen. This is necessary for calling the available ECIM services by your own applications. After subscription, the Service Provider of the service is notified of the submit action and gives authorization to developers to subscribe to the service/data. Visit My Subscriptions in ECIM platform main menu to see the services/data you have already subscribed and if the Service Provider has allowed you access to the service/data.

Your developer’s key will be created only when you have first subscribed to a service/data. To access it just visit My subscriptions in ECIM platform main menu.

Upon subscribing to a service, a developer key is created which allows the consumption of services through the ECIM platform. The Developer’s key is placed under the menu tab My Subscriptions. You can change it, by pressing the "Change key" button.

Getting a Developer Key is necessary to start using the ECIM API and calling the offered services as presented in the following paragraphs.

Visit My subscriptions in ECIM platform main menu. There, change  your Developer's key by pressing "Change key" button.

As a developer you have to subscribe to a web/data service to call it. After you have been confirmed by the service provider you can find more details of the service in the details page. To access the details page go to Marketplace and click on the service/data you wish to see details for.

A developer’s application doesn’t consume the service provider’s services directly, but instead always calls the platform’s web services, passing all the necessary data for the consumption of the registered services or the data. Therefore, one web service is used and more specifically the /callService method. This method receives the required parameters in JSON format and produces a JSON formatted response as well. It is a POST method which expects the parameters in the body of the POST message.

A developer has to be authorized by the service provider in order to see the necessary parameters required to call the particular ECIM service in the service’s details page. Moreover, a developer should use his developer key as parameter to the /callService method.

These parameters are presented below.

Base_url: the ECIM web service URL (http://ecim-dev.intrasoft-intl.com:8080/ecimServices/platform/mediator/)

Service method: The ECIM method name (/callService)

Parameters:

These parameters are presented below.

Base_url: the ECIM web service URL (https://platform.ecim-cities.eu/ecimServices/platform/mediator/)

Service method: The ECIM method name (/callService)

Parameters:

Input

Parameter

Value

Brief Description

serviceID

long, required

The id of the ECIM registered service to consume.

methodName

string, required

The service method name of the registered service to consume

serviceMediaType

string, required

The media type of the data the service accepts/returns. Currently application/JSON is supported.

developerKey

string, required

Developer’s key provided by ECIM.

bodyParameter

JSON Object

An object holding all the necessary parameters to be passed to the body of the request to the registered service.

serviceParameters

JSON array of JSON Objects (MethodParameter)

An array holding all the path, query or header parameters the registered service needs to be consumed without issues.

name

string, required

the name of the parameter

value

any primitive, required

the value of the parameter

Outputs

Parameter

Value

Brief Description

errorMsg

string, required

A message containing the error in case there was one, or empty if there is none.

serviceStatus

string, required

The service status message returned by the registered service

serviceResponse

JSON string, required

The response of the registered service

serviceCookies

JSON array

Holds one or more cookies returned by the registered service

serviceHeaders

JSON Object

Holds all the response headers returned from the registered service.

 

 

 

 

 

Request Example: The following example shows a request to the TestService parking service method (/parking) , which receives the longitude and the latitude as parameters and responds with the parking stations of this specific area.

The tool used to provide the service calls is the “REST console” plugin for Chrome.

In the figure , we make a POST request at

https://platform.ecim-cities.eu/ecimServices/platform/mediator/callService

with the following body

{

"serviceID": "2",

"developerKey" : {your_developerKey}},

"methodName": "parking",

"serviceMediaType": "json",

"serviceParameters":[{"name":"longitude", "value":50.82}, {"name":"latitude", "value":4.34}],

"bodyParameter": {}

}

 

 

 

The service response is a json-formatted message with the details of the original service response, as depicted in the following figure .

 

 

Request Example: The following example shows a request to the Demo Authentication API service method (/register) , which receives the body parameters and responds with an ecimID, a code and success/failure message.

The tool used to provide the service calls is the “REST console” plugin for Chrome.

In the figure , we make a POST request at

https://platform.ecim-cities.eu/ecimServices/platform/mediator/callService

with the following body

{
"serviceID": "160",
"developerKey" : {your_developerKey},
"methodName": "register",
"serviceMediaType": "json",
"serviceParameters":[],
"bodyParameter":{
"firstName":"test",
"lastName":"test",
"street":"test",
"postal":35,
"city":"test",
"country":"test",
"mobile":"434323",
"email":"test@gmail.com",
"licenseplate":"x1234",
"password":"test"}
}

 

To be able to call the data service (/callDataService) you need to know the following details, which are exposed after you have been confirmed by the data service provider.

Base_url: the ECIM web service URL (https://platform.ecim-cities.eu/ecimServices/platform/mediator/)

Service method: The ECIM method name (/callDataService)

Parameters:

Input

Parameter

Value

Description

serviceID

long, required

The ID of the ECIM registered service to consume.

serviceMediaType

string, required

The media type of the data the service accepts/returns. Currently application/JSON is supported.

developerKey

string, required

Developer’s key provided by ECIM.

Outputs

Parameter

Value

Brief Description

errorMsg

string, required

A message in case there was an error

serviceResponse

JSON string, required

The data provided in JSON format

 

 

 

 

 

Example: The following example presents a request to the MO4 parking sports service which responds with the parking stations of this specific area.

 

In the figure, we make a POST request at

https://platform.ecim-cities.eu/ecimServices/platform/mediator/callDataService

with the following body:

{

"serviceID": "8",

"developerKey" : {your_developerKey}}},

"serviceMediaType": "json"

}

 

 

The service response is a json-formatted message with the details of the original service response, as depicted in the following figure.

 

 

ECIM Platform allows service providers to register their services to the platform and take advantage of the benefits that a cloud infrastructure can offer.

As a Service Provider you have to take the following steps: Sign in > My Services on the top of the page of ECIM platform, to register your service. 

In order to publish a new service, you should go to My Services > My Web Services from the main menu. To register a new service, choose the "Add New Service" button. The edit screen appears.

 

 

Below we provide a detailed description of each of the field that the provider of the service should fill in. The fields with the red asterisk in the figure are mandatory.

Service name: The name of the service

Base URL: Access Url of the service

ECIM username: Authentication username for ECIM platform

ECIM password: Authentication password for ECIM platform

OAuth version: Open Authentication version that the service uses

Country: Country that the service concerns

Category: The main category of the service

Pricing info: Information about the pricing of the service

Price: The service price (if any)

Description: Description of the service

To immediately publish your service to Marketplace, click the “Publish service to Marketplace?” checkbox. By pressing the Submit button, a success notification message is displayed.

 

You can add a new service as described above, filling the fields of the new service. After the successful addition of the service you can edit or delete the service you have added. The following figures depicts an example of a filled-in form, the My Web Services page and the details of the service. 

 

 

 

 

 

In order to register a new data service, you should choose My Services > My Data Services from the menu. To register a new service, click the "Add New Data" button. The edit screen appears.

 

 

Below we provide a detailed description of each of the fields that the provider of the service should fill in. The fields with the red asterisk in the figure are mandatory.

Data Service Name: Name of the data service

URL: Access URL of the data service

ECIM username: Authentication username for ECIM platform

ECIM password: Authentication password for ECIM platform

Country: Country that the data service concerns

Release date: Date of formal issuance of the distribution

Update date: Most recent date on which the data service was changed, updated or modified

Category: The main category of the data service

Format: The file format of the distribution

Standard format: Metadata standard requirements

Language: The language used in the textual metadata

Publisher: The entity responsible for making the collection of metadata online

Frequency: The frequency at which the data service is published

Description: Description of the data service

Service image: Image of the service

To immediately publish your data to Marketplace, click the “Publish service to Marketplace?” checkbox. By pressing the Submit button, a success notification message is displayed.

You can add a new data service as described above, filling the fields of the new service. After the successful addition of the service you can edit or delete the service you have added. The following figure depicts an example of a filled-in form:

 

 

 

 

 

To see the subscriptions to your web/data services go to Service Access at the top of the page of ECIM platform. There, you can enable/disable user’s subscriptions.

When developers subscribe to a service, the provider of this service is responsible for allowing developers' subscriptions or not. In order to allow a developer’s subscription, you should press the Service Access tab in the main menu. The service access screen appears. Now you can allow a developer to have access to a service or data service by ticking the checkbox that corresponds to a particular developer and the subscribed service. You can always return to this screen and disable a developer’s subscription . The developer will receive an e-mail that informs him about your action (enable or disable his subscription).

 

The service/data statistics provided are the service subscriptions and service call and access statistics.

After selecting a particular service, a service details screen presents information concerning the service/data. Except the basic information, you can also see the number of users’ subscriptions to that particular service, methods of services, statistics about calls and access to this service/data.

 

 

 

Yes, as a Service Provider you can immediately publish your services to Marketplace, either when registering a new service/data or when editing it , by just checking the "Publish service to marketplace?" checkbox at the bottom of the page. You can always change this preference by going back and edit the service and unccheck this checkbox.

The Marketplace is where service providers and developers can publish or subscribe to a service respectively. The following sections present the main functionalities of the Marketplace and how the users can navigate through the sections and perform a number of activities.

 

In ECIM Marketplace you can find all the services and data that are available through the platform and are ready to be used as soon as you register. A Developer can browse the ECIM Marketplace either through the menu at the top of the page or by pressing the button "Browse Marketplace" at the Marketplace section of the page.

We provide details for each service or data available in the Marketplace. The basic information includes the name of the service/data, category, an indication of the operation of the service/data, the users’ rating and the pricing scheme followed (free/paid). There are also search and sorting availabilities for the presentation of the services.

 

 

After selecting a particular service, a service details screen presents information concerning the service/data. Except the basic information, you can also see the number of users’ subscriptions to that particular service, methods of services, statistics about calls and access to this service/data.

 

 

 

By going to My Services > My Web Services or My Services > My Data Service from the menu you can find the services or data services respectively that you have registered to the platform. If you click on the service or data service icon, you can view the details of your registered service. This screen presents information about the service or data service and also statistics about users’ subscriptions and calls (successful, failed, unauthorized) to the service.

 

 

There is also the opportunity of editing and deleting a registered service or data service. Under every registered service there are the edit and delete buttons that allow the provider to edit and delete the registered services. When pressing the "Edit" button, there is the ability to edit a previously added service. If the editing of the service is successful, you get a success message after pressing the "Submit" button.

 

 

If you decide to delete a service, you can achieve this by pressing the "Delete" button (which is placed under every service or data service in the My Services or My Data Services view). A confirmation window appears, and if you press “Yes”, the service is deleted.

Demo services are developed only for the Hackathons and the appChallenges that ECIM participates. They simulate approximately how the developers can build applications offering single-sign on and single payment solution to their applications. ECIM provides these services to the developers.

Service method: /ecim_registration

This service is a demo registration service using the ecimID provided by ECIM. It can be used only for demo mobility applications that will be developed by registered to ECIM platform developers for demo purposes.

Parameters:

 

Input

Parameter

Value

Brief Description

firstName

string, required

The first name of the user

lastName

string, required

The last name of the user

street

integer, required

Address street of the user

postal

integer, required

Address postal code of the user

city

string, required

City of the user

country

string, required

Country of the user

mobile

string, required

Mobile phone of the user

email

string, required

The e-mail of the user, which is checked if it is unique

licenseplate

string, required

Licence plate of the user’s car

password

string, required

Password that the user wishes to use for the new account

Outputs

Parameter and Value

 

Brief Description

status

JSON object, required

A status description which is consisted of a code and a message (both code and message declare if there is a failure or success).

ecimID

string, required

User’s id provided by ECIM

 
 

 

Service method: ecim_login

This service is a demo login service provided by ECIM using the ecimID. It can be used only for demo mobility applications that will be developed by registered to ECIM platform developers for demo purposes.

Parameters:

 

Input

Parameter

Value

Brief Description

email

string, required

The e-mail of the user

password

string, required

User's password 

Outputs

Parameter

Value

Brief Description

status

JSON object, required

A status description which is consisted of a code and a message (both code and message declare if there is a failure or success).

ecimID

string, required

User’s id provided by ECIM

 

 

 

Service method: ecim_transaction_authorization

This service is an authorization service for Payment Transactions using the ecimID and the developers key that are provided by ECIM. It can be used only for demo mobility applications that will be developed by registered to ECIM platform developers for demo purposes.

Parameters:

 

Input

Parameter and Value

 

Brief Description

email

string, required

The e-mail of the user

ecimID

string, required

Ecim id of the user

amount

double, required

Amount of the transaction

developerKey

string, required

Developer’s key provided by ECIM

Outputs

Parameter

Value

Brief Description

authorizationID

string, required

Id of the given authorization

status

JSON object, required

A status description which is consisted of a code and a message (both code and message declare if there is a failure or success).

date

timestamp, required

Date of the authorization

ecimID

string, required

User’s id provided by ECIM

 

 

Service method: ecim_payment

This is a service to commit demo payment using the authorizationID from the demo authorization service of ECIM the ecimID and the developers key that are provided by ECIM. It can be used only for demo mobility applications that will be developed by registered to ECIM platform developers for demo purposes.

Parameters:

 

Input

Parameter

Value

Brief Description

email

string, required

The e-mail of the user

ecimID

string, required

The ecim id of the user

amount

double, required

The amount of the transaction

developerKey

string, required

Developer’s key provided by ECIM

authorizationID

string, required

The id of the required transaction authorization

Outputs

Parameter

Value

Brief Description

transactionID

string, required

The id of the given transaction

status

string, required

A status description which is consisted of a code and a message (both code and message declare if there is a failure or success).

date

timestamp, required

Date of the transaction

ecimID

string, required

User’s id provided by ECIM

message

JSON object, required

Message that gives details about the transaction

authorizationID

string, required

The id of the required transaction authorization

 
 
 

Service method: ecim_transaction_status

This service is a demo service to report the success or a failure of a demo payment using the ECIM demo services for payment transactions. It can be used only for demo mobility applications that will be developed by registered to ECIM platform developers for demo purposes.

Parameters:

 

Input

Parameter

Value

Brief Description

providerID

string, required

Provider’s id of the service

transactionID

string, required

Id of the transaction

Outputs

Parameter

Value

Brief Description

status

string, required

A status description which declares if there is a failure or success

date

timestamp, required

Date of the transaction

message

JSON object, required

Message that gives details about the transaction

As an ECIM user can deactivate your account by sending an email to the ECIM administrator. If you have decided to deactivate your account please click here.