s3-eu-west-1.amazonaws.coms3-eu-west-1.amazonaws.com/stm-stmvalidation/uploads/... · Web viewservice and its building blocks in a technology-independent way, according to the guidelines

Document No: Title: SeaSWIM Connector Service Specification

Date: 2023-05-17

AuthorsName OrganisationFabio Renda CIMNE

Document HistoryVersion Date Initials DescriptionVersion 0.1 2016-09-05 FR, MO Draft version

Version 0.2 2016-10-27 FR, MO Updated descriptions

Version 0.3 2016-11-09 ON, FR Updated descriptions

ReviewName OrganisationMikael Olofsson SMAPer Löfbom SMAOliver Norkus University of Oldenburg

Page 2 of 23

Table of contents

1 Introduction....................................................................................................................................................................1.1 Purpose of the document..............................................................................................................................................1.2 Intended readership.......................................................................................................................................................1.3 Inputs from other projects.............................................................................................................................................

2 Service identification.....................................................................................................................................................2.1 Functional and non-functional Requirements...............................................................................................................2.2 Other Constraints..........................................................................................................................................................2.2.1 Relevant Industrial Standards....................................................................................................................................2.3 Operational Nodes........................................................................................................................................................2.4 Operational Activities...................................................................................................................................................

3 Service Overview...........................................................................................................................................................3.1 Service Interfaces..........................................................................................................................................................

4 Service Data Model........................................................................................................................................................4.1 SSC Service Data Exchange Model.............................................................................................................................4.1.1 callServiceRequestObj.............................................................................................................................................4.1.2 requestType..............................................................................................................................................................4.1.3 callServiceResponseObj..........................................................................................................................................4.1.4 findIdentitiesRequestObj.........................................................................................................................................4.1.5 findIdentitiesResponseObj.......................................................................................................................................4.1.6 findServicesRequestObj..........................................................................................................................................4.1.7 findServicesResponseObj........................................................................................................................................4.1.8 identityRegistryGeneralRequestObj........................................................................................................................4.1.9 identityRegistryGeneralResponseObj......................................................................................................................4.1.10 serviceRegistryGeneralRequestObj.......................................................................................................................4.1.11 serviceRegistryGeneralResponseObj....................................................................................................................

5 Service Interface Specification...................................................................................................................................5.1 SeaSWIM Connector Service.....................................................................................................................................5.1.1 SeaSWIM Connector Service Private Interface......................................................................................................

6 Service Dynamic Behaviour........................................................................................................................................6.1 Interaction - callService..............................................................................................................................................6.2 Interaction - findServices............................................................................................................................................6.3 Interaction - findIdentities..........................................................................................................................................6.4 Interaction - <incomming call>..................................................................................................................................6.5 Interaction - <start-up>...............................................................................................................................................

7 Service Provisioning....................................................................................................................................................

8 References.....................................................................................................................................................................

9 Acronyms and Terminology.......................................................................................................................................

Page 3 of 23

1 Introduction1.1 Purpose of the documentThe purpose of this service specification document is to provide a holistic overview of the Voyage Information service and its building blocks in a technology-independent way, according to the guidelines. It describes a well-defined baseline of the service by clearly identifying the service version.The aim is to document the key aspects of the Information service at the logical level:

the operational and business context of the serviceo requirements for the service (e.g., information exchange requirements)o involved nodes: which operational components provide/consume the serviceo operational activities supported by the serviceo relation of the service to other services

the service descriptiono service interface definitionso service interface operationso service payload definitiono service dynamic behaviour description

service provision and validation aspects

1.2 Intended readershipThis service specification is intended to be read by service architects, system engineers and developers in charge of designing and developing an instance of the Information service.Furthermore, this service specification is intended to be read by enterprise architects, service architects, information architects, system engineers and developers in pursuing architecting, design and development activities of other related services.

Page 4 of 23

1.3 Inputs from other projectsUses the Service and Identity Registry from the EfficienSea2 project.

2 Service identificationName SeaSWIM Connector Proxy Service

ID urn:mrn:stm:service:specification:cimne:ssc

Version 0.3

Description The service encapsulates functionality to connect to SeaSWIM. The service supports with SeaSWIM authentication on both outgoing and incoming service calls. The SSC also supports search in Identity and Service Registry.

Keywords SSC, SeaSWIM Connector

Status provisional

Page 5 of 23

2.1 Functional and non-functional RequirementsRequirements overview:

Requirement Id SSC001Requirement Name SSC001 - Enable safe connection between services in the STM infrastructureRequirement Text SSC take care of the communication between the services following the

architecture specifications of the STM project. Implement safe SSL communication between services using STM certificates

RationaleAuthor STMReference

Requirement Id SSC002Requirement Name SSC002 – Enable execute communications requests between the services Requirement Text SSC offer a communication interface in order to execute request with the other

services.


Requirement Id SSC003Requirement Name SSC003 – Handle the communication with the Service RegistryRequirement Text SSC can communicate with the service registry to retrieve service instance list.

SSC enable to execute general request against the Service Registry


Requirement Id SSC004Requirement Name SSC004 – Handle the communication with the Identity RegistryRequirement Text SSC use the ID registry to validate the identities, retrieve the identities list and

execute general request against the Identity registry


Requirement Id SSC005Requirement Name SSC005 – Expose a set of private functions that will be used by the application

serviceRequirement Text SSC is controlled by a set of interfaces.


Page 6 of 23

2.2 Other ConstraintsNo information.

2.2.1 Relevant Industrial Standards

http ov er TLS

tagsLink = https://tools.ietf.org/html/rfc2818

SSL protocol version 3

tagsLink = https://tools.ietf.org/html/draft-ietf-tls-ssl-version3-00

X.509

tagsLink = https://tools.ietf.org/html/rfc4158

OpenId

tagsLink = http://openid.net/

2.3 Operational NodesThe SeaSwimConnector is the entry point to the STMinfrastructure. The main objective are: - help the application service to communicate with the Service registry and Identity registry- help the communication between services part of the STM infrastructure- cut the integration barrier for an application service that want to join to STM infrastructure

2.4 Operational ActivitiesNo information.

Page 7 of 23

3 Service Overview

«service»SeaSWIM Connector Serv ice

«Interface»SeaSWIM Connector Serv ice Priv ate Interface

+ callService(callServiceRequestObject): callServiceResponseObj+ findIdentities(findIdentitiesRequestObj): findIdentitiesResponseObj+ findServices(findServicesRequestObj): findServicesResponseObj+ identityServiceRequest(identityRegistryGeneralRequestObj): identityRegistryGeneralResponseObj+ registryServiceRequest(serviceRegistryGeneralRequestObj): serviceRegistryGeneralResponseObject

«abstract interface»Identity Registry Serv ice

«abstract interface»Serv ice Registry Serv ice

3.1 Service Interfaces

Service Interface Role Service OperationSeaSWIM Connector Service Private Interface

Provided callServicefindIdentitiesfindServicesidentityServiceRequestregistryServiceRequest

Page 8 of 23

4 Service Data Model

4.1 SSC Service Data Exchange Model

«enumeration»requestType

GET POST DELETE PATCH

callServ iceResponseObj

- statusCode: int- body: string [0..1]

callServ iceRequestObject

- requestType: requestType- endpoint_method: URI- body: string [0..1]- headers: string [0..*]

findServ icesRequestObj

- keyword: string- organisationId: URN- coverageArea: string- serviceDesignId: URN- serviceId: URN

findServ icesResponseObj

- statusCode: int- body: string [0..*]

findIdentitiesRequestObj

- organisationId: URN [0..1]findIdentitiesResponseObj

- statusCode: int- body: string [0..*]

identityRegistryGeneralRequestObj

«XSDelement»+ typeRequest: requestType+ headers: string [0..-1]+ body: string [0..1]

«XSDtopLevelElement»identityRegistryGeneralResponseObj

+ statusCode: int

«XSDelement»+ body: string

«XSDtopLevelElement»serv iceRegistryGeneralRequestObj

«XSDelement»+ typeRequest: requestType+ header: string [0..-1]+ body: string [0..1]

«XSDtopLevelElement»serv iceRegistryGeneralResponseObject

+ statusCode: int

«XSDelement»+ body: string

Page 9 of 23

4.1.1 callServiceRequestObjContain the data needed by the callService function to execute the request. The parameters contained in the callServiceRequestObj are the general parameters contained in a standard HTTP request.

Element Name AttributescallServiceRequestObj

Name Type DescriptionrequestType requestType GET or POST or DELETE or PATCH

endpointMethod URI URL contains <ipaddress>:<port>/<request>

body string Request body needed by the requested service

headers string Request headers needed by the requested service

4.1.2 <enumeration> requestType

Element Name Enumeration ValuesrequestType

Name Type DescriptionGET stringPOST stringDELETE stringPATCH string

4.1.3 callServiceResponseObjThis object is a response container with response from called service

Element Name AttributescallServiceResponseObj

Name Type Descriptionbody string Request Body

statusCode int HTTP Status codes

4.1.4 findIdentitiesRequestObj

Element Name AttributesfindIdentitiesRequestObj

Name Type DescriptionorganisationId URN Organisation id in MRN format

Page 10 of 23

Page 11 of 23

4.1.5 findIdentitiesResponseObj

Element Name AttributesfindIdentitiesResponseObj

Name Type Descriptionbody string Response from Identity Registry


4.1.6 findServicesRequestObj

Element Name AttributesfindServicesRequestObj

Name Type Descriptionkeyword string Example: #VIS#

organisationId URN Servie provider id in MRN format

coverageArea string UnLoCode,wkt,Location,geoJson

serviceDesignId URN Service Design Id in MRN format

serviceId URN Service id in MRN format

4.1.7 findServicesResponseObj

Element Name AttributesfindServicesResponseObj

Name Type Descriptionbody string TBD


4.1.8 identityRegistryGeneralRequestObj

Element Name AttributesidentityRegistryGeneralRequestObj

Name Type DescriptiontypeRequest requestTyp

eurl string

Page 12 of 23

headers stringbody string

4.1.9 identityRegistryGeneralResponseObj

Element Name AttributesidentityRegistryGeneralResponseObj

Name Type Descriptionbody string Like described in the identity registry data

model description


4.1.10 serviceRegistryGeneralRequestObj

Element Name AttributesserviceRegistryGeneralRequestObj Name Type Description

typeRequest requestType GET/POST/PATCH/DELETEurl stringheaders stringbody string

4.1.11 serviceRegistryGeneralResponseObj

Element Name AttributesserviceRegistryGeneralResponseObj Name Type Description

body stringstatusCode int HTTP Status codes

Page 13 of 23

5 Service Interface Specification

5.1 SeaSWIM Connector Service

5.1.1 SeaSWIM Connector Service Private Interface

5.1.1.1.1 callService()Facilitate the communication between services. The function will call a generic web service part of the stm infrastructure, checking the certificates authentications.

Operation functionalityRetrieve the contacted service response.

Operation ParametersParameter Name Direction Data Type DescriptioncallServiceObj Input callServiceRequestObj

Return Direction Data Type DescriptionReturn callServiceResponseO

bj

5.1.1.1.2 findIdentities()Facilitate the communication with the identity service in order to discover the organizations part of the STM infrastructure.

Operation functionalityRetrieve a list of organizations part of the STM infrastructure

Operation ParametersParameter Name Direction Data Type DescriptionfindOrganizationsObj Input findIdentitiesRequestO

bj

Return Direction Data Type DescriptionReturn findIdentitiesResponse

Obj

5.1.1.1.3 findServices()Facilitate the communication with the service registry service in order to discover services of the STM infrastructure.

Operation functionalityRetrieve list of services instances, filtered by parameters in order to contact the right web services endpoints.

Operation ParametersParameter Name Direction Data Type DescriptionfindServiceObj Input findServicesRequest

Obj

Return Direction Data Type DescriptionReturn findServicesResponse

Obj

Page 14 of 23

5.1.1.1.4 identityServiceRequest()Enable a general request against the identity registry

Operation functionalityExecute general rest request against the Identity Registry exposed rest api

Operation ParametersParameter Name Direction Data Type DescriptionidentityServiceRequestObj

Input identityRegistryGeneralRequestObj

Return Direction Data Type DescriptionReturn identityRegistryGenera

lResponseObj

5.1.1.1.5 registryServiceRequest()Enable a general request against the service registry.

Operation functionalityExecute general rest request against the Service Registry exposed rest api.

Operation ParametersParameter Name Direction Data Type DescriptionregistryServiceRequestObj

Input serviceRegistryGeneralRequestObj

Return Direction Data Type DescriptionReturn serviceRegistryGenera

lResponseObj

Page 15 of 23

6 Service Dynamic Behaviour

CALL service https://callService

findServiceService Registry (to central service)

findIIdentitiesIdentity Registry (to central service)

intercepted incoming service callforward authenticated

service request

«block»SeaSWIM Connector v2

CALL service https://callService

findServiceService Registry (to central service)

findIIdentitiesIdentity Registry (to central service)

intercepted incoming service callforward authenticated

service request

«functional block»Call Service

«functional block»Check Authentication

«functional block»Forward call to Service Registry to find service

instance(s)

«functional block»Configuration

«functional block»Get entity IDs with

presentable information

«functional block»Handle incoming service call

Page 16 of 23

6.1 Interaction - callServiceThe SeaSWIM Connector service support with mutual authentication and HTTPS through the operation callService. The operation is generic and transparent and the user is responsible for providing the correct endpoint, request type, header/parameters and body according to the consumed service description.

«Interface»SeaSWIM Connector Service

Private Interface

Service: ConsumerInterface

Application:Consumer Interface

:response

mutual authenticatrion()

<https service call>()

callService(callServiceRequestObj)

:callServiceResponseObj

do Work()

mutual authentication()

Prepare the service call()

Page 17 of 23

6.2 Interaction - findServicesSupports with search in Service Registry for service instances to consume that matches the provided search parameters.

Search can be done based on service keywords, geolocation or service design.

Supports with search in Service Registry for service instances to consume that matches the provided search parameters.

Search can be done based on service keywords and geolocation.



Private Interface

:Service RegistryService

:List of Service instance descriptions

login'()

findServices(findServicesRequestObj)

:findServicesResponseObj

getInstances / _searchX()

Prepare the call to Service registry()

Page 18 of 23

6.3 Interaction - findIdentities

Supports with search in Identity Registry.Currently a complete list of organization identities are returned based on access rights in Identity Registry.



Private Interface

:Identity RegistryService

:findIdentitiesResponseObj

get()

findIdentities(findIdentitiesRequestObj)

:List of identities

prepare call()

Page 19 of 23

6.4 Interaction - <incomming call>The SeaSWIM Connector proxy service intercepts the incoming service request, handles authentication and, if source is authenticated, forwards the service call to the "master" service endpoint.

The SeaSWIM Connector proxy service intercepts the incoming service request, handles authentication and, if source is authenticated, forwards the service call to the "master" service endpoint.

:Consumer InterfacePrivate: ProducerInterface

The incomming service call is "picked up" be the proxy service (SSC)

«Service»SeaSWIM Connector Service

:https response

forward cal l to http <service cal l>()


:response


https <service call>()

6.5 Interaction - <start-up>

«Service»SeaSWIM Connector Service

readConfigurationFile()

Page 20 of 23

7 Service Provisioning The SeaSWIM Connector proxy service is intended to be used in cooperation with a “master” (application) service to support with SeaSWIM interactions.

8 ReferencesReference name Comment LinkSeaSWIM Technical Documentation

9 Acronyms and Terminology

9.1 AcronymsTerm DefinitionAPI Application Programming InterfaceMEP Message Exchange PatternREST Representational State TransferSSC SeaSWIM ConnectorURN Uniform Resource LocatorXML Extendible Mark-up LanguageXSD XML Schema Definition

9.2 TerminologyTerm Acronym DefinitionExternal Data Model Describes the semantics of the “maritime world” (or a

significant part thereof) by defining data structures and their relations. This could be at logical level (e.g., in UML) or at physical level (e.g., in XSD schema definitions), as for example standard data models, or S-100 based data produce specifications.

SourceE2 D3.4 Service Documentation Guidelinesv01.01

Service The provision of something (a non-physical object), by one, for the use of one or more others, regulated by formal definitions and mutual agreements. Services involve interactions between providers and consumers, which may be performed in a digital form (data exchanges) or through voice communication or written processes and procedures.


Service Data Model Formal description of one dedicated service at logical level. The service data model is part of the service specification. Is typically defined in UML and/or XSD. If an external data model exists (e.g., a standard data model), then the service data model shall refer to it: each data item of the service data model shall be mapped to a data item defined in the external data model.

Page 21 of 23


Service Technical Design The technical design of a dedicated service in a dedicated technology. One service specification may result in several technical service designs, realising the service with different or same technologies.


Service Endpoint A Service Endpoint is the URL where your service can be accessed by a client application. The same web service can have multiple endpoints, for example in order to make it available using different protocols.

Sourcehttp://stackoverflow.com/questions/9807382/what-is-a-web-service-endpoint

Service Operation Functions or procedure which enables programmatic communication with a service via a service interface.


Service Parameters Service Parameters are input to a Service Operation and can be described formally in a data exchange model as e.g. XML Schemas.

SourceMO

Service Response Service Response are output from a Service Operation and can be described formally in a data exchange model as e.g. XML Schemas.

SourceMO

Service Consumer A service consumer uses service instances provided by service providers. All users within the maritime domain can be service customers, e.g., ships and their crew, authorities, VTS stations, organizations (e.g., meteorological), commercial service providers, etc.


Service Provider A service provider provides instances of services according to a service specification and service instance description. All users within the maritime domain can be service providers, e.g., authorities, VTS stations, organizations (e.g., meteorological), commercial service providers, etc.

Source

Page 22 of 23

E2 D3.4 Service Documentation Guidelinesv01.01

Service Request

Source

Page 23 of 23

Documents

s3-eu-west-1.amazonaws.coms3-eu-west-1.amazonaws.com/stm-stmvalidation/uploads/... · Web viewservice and its building blocks in a technology-independent way, according to the guidelines