ArtDatabankenSOA

Last changed: 21 February 2017

ArtDatabankenSOA is a collection of collaborating web services that handles data that are managed by Swedish Species Information Center (ArtDatabanken). The web services are platform-independent. This means they can be used by any computer operating system and clients can be created in any computer language and tools that support SOAP.

Available types of data

Geographical region

Information about different types of regions in Sweden. For example enumeration of provinces, counties and municipalities. Geographical regions are handled by the web service GeoReferenceService.

Reference

References are used to specify source of information. References are handled by web service ReferenceService.

Species observation

Observations of species in nature. Several of the participants in Swedish LifeWatch will provide species observations in the future. Species observations can be retrieved from the web service SwedishSpeciesObservationService. Species observations that have Swedish Species Information Center as initial source are managed by web application Species Observations System (Artportalen).

Taxon attribute

Taxon attributes are facts related to species (or more precisely taxa) that are stored in a database. For example most of the information about red-listed species in Sweden are stored as species facts. Taxon attributes are handled by the web service TaxonAttributeService.

Taxonomy

Taxonomy is the foundation when attaching data to species. Taxonomy are provided by the web service TaxonService and managed by the web application Dyntaxa.

User

Information about users of Swedish Species Information Center's applications and web services. User information are handled by the web service UserService and the web application UserAdmin.

Web services in ArtDatabankenSOA

Web service status

Current status for SOAP based web services can be viewed in the webb application WebAdministration.

Reference documentation

Detailed documentation is available online on address: https://doc.artdatabankensoa.se/WebService/

Client data layer

Swedish Species Information Center has created a client data layer for internal use. Those who want to use the web services in ArtDatabankenSOA may choose to use our client data layer. This client data layer is plattform specific and uses Microsoft .NET Framework version 3.5. The data layer consists of some Dynamic-link libraries (DLL) and can be downloaded from the following link:

It is optional but recommended to use this client data layer. Last update of these dll's was done 2017-01-30.

Benefits when using the client data layer

  • Object oriented: Web services are not object oriented but the client data layer is.
  • Hides communication: Communication is handled by the client data layer.
  • Efficiency: Client data layer handles data efficiently, for example with the help of caching.
  • Shorter development time: A lot of code are already created and tested.

All web services uses the client data layer.

Technical details about web services

Generic data

Normally data in data types are handled with named fields with type suitable for the specified field but all web services have the possibility to handle data that is transported as generic data. Generic data is data that are transported in field WebData.DataFields. All data types that are handled over Internet have this field WebData.DataFields. WebData.DataFields contains a collection of fields of type WebDataField where each WebDataField has one piece of information. Values for all data types are transported as text, this means that clients must know how to convert a text representation to the actual data type. Generic data are used when data types handled by a web services are updated but you do not want to break the web service contract. Generic data may also be used when handling data types that returns a flexible collection of fields.

How to convert a string to different data types:

  • Boolean: String has value "True" or "False".
  • DateTime: Format is YYYY-MM-DDTHH:mm:ss.fffffff, for example 1998-01-01T00:00:00.0000000.
  • Float: Handled as a double-precision 64-bit number that complies with the IEC 60559:1989 (IEEE 754) standard for binary floating-point arithmetic. Format is D.DDDDDDDDDDE+or-DDD. for example 3.1415926536E+000. May have a leading minus sign.
  • Int32: A sequence of digits without spaces or commas, for example 6258250. May have a leading minus sign.
  • Int64: A sequence of digits without spaces or commas, for example 43254236258250. May have a leading minus sign.
  • String: No conversion, contains actual value.

Language handling

The goal is that all web services should be able to handle multiple languages but currently support for multiple languages are limited. Only UserService supports multiple languages.

How support for multiple languages are handled:

When the client makes a call to the Login method in the web service returned data are in the language that the person has set in the user administration system. Default language, if no language has been set, is brittish english. Information about used language is returned in property WebLoginResponse.Locale as part of the the login respons. When further calls to the web service are made desired language are sent in property WebClientInformation.Locale. The client may change language whenever it wants.

Protocols

All web services in ArtDatabanken SOA support both SOAP 1.1 and SOAP 1.2. For efficiency reasons Swedish Species Information Center uses a Microsoft specific binary format for internal use. All web services have three endpoints that supports the three different protocols.

  • SOAP 1.1 has the base address of the web service. For example https://User.ArtDatabankenSoa.se/UserService.svc
  • SOAP 1.2 has extension /SOAP12 added to the base address. For example https://User.ArtDatabankenSoa.se/UserService.svc/SOAP12
  • Binary format has extension /Fast added to the base address. For example https://User.ArtDatabankenSoa.se/UserService.svc/Fast

WSDL description of a web services can be retrived by adding ?wsdl to the base address of the web service. For example https://User.ArtDatabankenSoa.se/UserService.svc?wsdl

Transaction handling

About the transaction handling:

Transaction implementation is ArtDatabankenSOA specific. It does not rely on WS-Transaction or any other predefined transaction handling. The reason for this is that several protocols (see section Protocols above) are supported and no predefined transaction handling works in all used protocols. Using a transaction implementation that works independent of protocol also means fewer demands on clients. Transaction handling is only implemented in web services that creates or updates data. Distributed transaction handling is not supported in web services.

How transaction handling works:

A transaction starts with a call to the method StartTransaction which has a parameter that specifies a timeout limit. If data are successfully update the client makes a call to the method CommitTransaction. If something goes wrong in data handling client makes a call to method RollbackTransaction. A call to method RollbackTransaction is automatically made if transaction is not ended inside the specified timeout limit.

User session

A user must login to a web service before any other methods in the web service are called. If several web services in ArtDatabankenSOA are used the user must login once to each web service. Login is made by a call to the Login method which on successful login returns a security token. This security token must be kept by the client application and is provided in further calls to the web service. When the user has finished using the web service a call to the method Logout should be made.


Contact

Björn Karlsson, System developer
The Swedish Species Information Centre, SLU
bjorn.karlsson@slu.se, 018-672679