Data Service API Documentation

Overview

Scale-up Suite Dynochem, Reaction Lab and Numero provide tools to search and obtain data from external data sources via a common web service API (Scale-up Data Service API).

Alongside Data Services provided by Scale-up Systems, additional Data Services can be deployed and listed to allow users access to e.g. company internal Materials or other relevant project information.

The listing mechanism provides administrators with access control mechanisms to decide, who should avail of respective services. Services can reside securely on company internal networks. Scale-up Suite clients will connect directly to listed services if users are on the internal network or connected via VPN (see "Security and Logging" below).

The API provides the following operations

Operation	Input	Returns
Search	Text to be searched	A list of search results with up to 4 property values (displayed in a table). Optional chemical structure definition or bitmap image as tooltip
Fetch	A list of item IDs	A list of items with properties (name/value pairs, optional unit, can be images or chemical structure definition)

Service Types - General and Materials

Data Services can be listed as being General or Materials services. Both service types are acessible from Dynochem and Numero, which are designed to access all kinds of data. Only Materials Services are accessible from the Rection Lab materials search.

Materials Services implement the same API definition as General Services, but search results must return specific values as defined below.
If a Structure is provided it will be shown in a tooltip, otherwise the Image will be displayed (if provided).

Value	Data	Required	Example
Value1	CAS Number	Yes	"67-56-1"
Value2	Name	Yes	"MEOH"
Value3	Formula	Yes	"CH4O"
Value4	Long Name	Yes	"Methanol"
Structure	Chemical structure definition Byte array as base64 string Supported formats: .cdxml, .cdx, .mol, .sdf, .rxn	No	"DDFcrrpDRDAxMDAEAwI[...]"
Image	base64 string representing a bitmap image as byte array	No	"VmpDRDAxMDAEAwI[...]"

Fetch results are expected to return the properties listed below with the defined property names (case sensitive). Additional properties can be returned to be available in Catalist.

Property Name	Value	Example
CAS	CAS Number	"67-56-1"
Formula	Chemical formula	"CH4O"
MW	Molecular Weight	32.0418
Aliases	Array of names	["MeOH","Methyl alcohol"]
Structure	Chemical structure definition Byte array as base64 string Supported formats: .cdxml, .cdx, .mol, .sdf, .rxn Can be null	"VmpDRDAxMDAEAwI[...]"

See the API Reference for further details.

Requirements

Scale-up Suite Client

Scale-up Suite: Build ID 2.0.0bXXX or later
A Scale-up User Account
A valid license for the relevant product:
- Reaction Lab Materials Search is available with Reaction Lab
- Properties and Catalist for Microsoft Excel are available with Dynochem
- Properties, Catalist and Plaintext for Microsoft Word, Outlook or PowerPoint are available with Numero

Web Server hosting the API

Server type: Any
Implementation language or technology: Any
Protocol: HTTPS
Network access: from Scale-up Suite client (can be limited to an internal network/VPN or restricted IP addresses)

API Reference and Implementation

An interactive reference with underlying sample service is provided at API Reference

An Open API definition (Swagger 2.0) is provided at
From this server stubs can be generated in many languages using tools like Swagger Hub

Property Definitions

Property definitions for items in fetch results have the following attributes

Attribute Name	Data Type	Description	Required	Example
Name	string	The property name to be displayed	Yes	"Distance"
Value	object	See data type definitions below	Yes	5.9
Unit	string	Optional unit of measure	No	"km"
Usage	string	null or usage definition for specific string values	See data type definitions below	null

The following data types can be sent as property values

Data Type	Description	Unit	Usage Value	Example	Rendered as
Numeric	integer or decimal value	optional	null	{ "name": "Distance", "value": 5.9, "unit": "km", "usage": null }	Number formatted in current culture, e.g: [en-UK] Distance: 5.9 km [de-DE] Distance: 5,9 km
Boolean	true/false	null	null	{ "name": "Approved", "value": true, "unit": null, "usage": null }	Approved: True
Text	string	optional	null	{ "name": "Address Field 1", "value": "4 Privet Drive", "unit": null, "usage": null }	Address Field 1: 4 Privet Drive
Link	string starting with http://, https://, mailto: or file://	null	null	{ "name": "Website", "value": "http://scale-up.com", "unit": null, "usage": null }	Website: http://scale-up.com
Email	string representing a single email address	null	null	{ "name": "Email", "value": "user@example.com", "unit": null, "usage": null }	Email: user@example.com
Date Time	string in internet "date-time" format	null	null	{ "name": "Created", "value": "2011-09-07T09:00:56", "unit": null, "usage": null }	Full date time in current culture, e.g: [fr-FR] Created: 07/09/2011 09:00:56 [en-US] Created: 9/7/2011 09:00:56
Date Time Formatted	string in internet "date-time" format	null	.NET date-time format string	{ "name": "Date of Birth", "value": "1987-10-07T00:00:00", "unit": null, "usage": "d" }	d = Short date in current culture, e.g: [fr-FR] Date of Birth: 07/10/1987 [en-US] Date of Birth: 10/7/1987
Bitmap Image	base64 string representing a bitmap image as byte array	null	"Image"	{ "name": "Graph", "value": "VmpDRDAxMDAEAwIBAA[...]", "unit": null, "usage": "Image" }	Graph: [Image icon] Image preview on rollover Full image can be inserted into the document
Chemical Structure	base64 string representing a chemical structure definition as byte array Supported formats: .cdxml, .cdx, .mol, .sdf, .rxn	null	"Structure"	{ "name": "Structure", "value": "DRDAxMDAfgRDyeEAwIBAA[...]", "unit": null, "usage": "Structure" }	Structure: [Structure icon] Structure preview on rollover Full structure image can be inserted into the document
Array	One level deep array with values of type string, Boolean or numeric (can be mixed)	null	null	{ "name": "Specification", "value": ["Steel", 1.8, true], "unit": null, "usage": null }	Values displayed as comma delimited string Specification: Steel, 1.8, True

For more details see the ItemProperty model definition in the API Reference

Client Configuration and Listing

Scale-up Suite clients require the following information to connect to a Data Service

Item	Value	Example
Endpoint	The url for the Data Service	https://apidocs.scale-up.com/v1
Service Type	General or Materials	General
Version	API version (currently always 1.0)	1.0
API Key	A text value that Scale-up Suite clients submit when making API requests (optional)	test-key-1
Service Name	Descriptive name for the Data Service	Example Time Zone Look-up
Owner	Owner name	Scale-up Systems
Description	Descriptive information Will be shown on error or connection failure Should include connection requirements if restricted	Example Data Service for development and test purposes. (Local network access or VPN required)
Contact Email	Email address of a local administrator Will be shown on error or connection failure	serviceadmin@example.com
Host Type	Public or Internal Use Internal to identify services hosted on an internal network/VPN or a public server with IP address restrictions	Internal

Clients can be configured in two ways.

File Configuration for Development and Testing

A DataServices.xml file can be placed at %UserProfile%\AppData\Roaming\Scale-up Systems\Scale-up Suite using the following format.

    <?xml version="1.0" encoding="utf-16"?>
    <ArrayOfServiceReference xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
        <ServiceReference>
            <EndPoint>https://apidocs.scale-up.com/v1</EndPoint>
            <Type>General</Type>
            <Owner>Scale-up Systems</Owner>
            <Version>1.0</Version>
            <ApiKey>test-key-1</ApiKey>
            <ServiceName>Example Time Zone Look-up</ServiceName>
            <Description><![CDATA[Example Data Service for development and test purposes]]>
            </Description>
            <AdminEmail>serviceadmin@example.com</AdminEmail>
        </ServiceReference>
    </ArrayOfServiceReference>

Service Listing for End User Access

A service can be submitted to support@scale-up.com to be listed for end user access. The initial listing will also define at least one Data Service administrator.

Data Service administrators can access the listing administration dash board from their Scale-up User Profile. Via the dashboard administrators can:

Enable or disable the service
Change the end point or other properties
Assign service users by email address
Add or remove other administrators

Email domains can be defined for a Data Service on a demand, which will automatically give all Scale-up Suite users with an email address matching the specific domain access.

End users get access to the service by refreshing the Scale-up Manager.

Security and Logging

API Key and Logging Data

An API key can be specified for data services, which Scale-up Suite clients will send with Search and Fetch requests alongside the data identified below, all of which which can be used to control access to a Data Service, logging or diagnostics. API keys sepecified for a listed service are securely managed and never exposed to users. All web requests require HTTPS.

Parameter Name	Value	Sent In	Example
API_KEY	The API Key value specified in the file configuration or listing	Header	test-key-1
userName	The email address/username of the Scale-up Suite user	Body	user@example.com
buildNumber	The build number of the Scale-up Suite client	Body	2.0.0b567
applicationId	The executing client application Reaction Lab \| Excel \| Word \| PowerPoint \| Outlook	Body	Excel
clientId	The executing client component Materials Search \| Catalist	Body	Catalist
serviceIdentifier	The service identifier as defined in the Scale-up Data Service listing Can be used to make service distinctions in case the same endpoint is used for distinctive data sets to be listed individually	Body	Example-Data-Service-123456
serviceVersionNumber	The version number as defined in the Scale-up Data Service listing	Body	1.0

Deployment

Data Services can be hosted on an internal network, ensuring that only users with direct or VPN access to that network can connect to the service, or on a public network with IP address restrictions that ensure only users on certain networks get access.

If hosted on a publicly accessible server, the API Key can be used to allow access only to trusted clients.