Connector HTTP API Reference

The purpose of this API is to provide device software and firmware with the ability to communicate with West Connectivity. Devices use this API to perform actions such as authentication, posting sensor and status data, and retrieving configuration and control updates.

Info

Your hardware & Library MUST be compatible with Connectivity TLS Specs., make sure you read it first.

Note

When used in this document, "timestamp" is a Unix timestamp, defined as the number of seconds that have elapsed since 00:00:00 Coordinated Universal Time (UTC), Thursday, 1 January 1970.

General

HTTP Responses

Typical HTTP response codes include:

Code	Response	Description
200	OK	Successful request, returning requested values
204	No Content	Successful request, nothing will be returned
4xx	Client Error	There was an error* with the request by the client
401	Unauthorized	Missing or invalid credentials
5xx	Server Error	Unhandled server error. Contact support.

Note

Aliases that are not found are not considered errors in the request. See the documentation for write, read, and Hybrid Read Write for details.

Libraries and Sample Code

Sample code that uses this API can be found on the West Connectivity Getting Started product examples:

Notational Conventions

This document uses the following notational conventions:

A name in angle brackets (e.g., <myvar> is a placeholder that will be defined elsewhere)
... represents one or more of the previous items
Curly brackets around HTTP headers represent optional or conditional headers.

Encoding

As of Content-Type: application/x-www-form-urlencoded Non-alphanumeric characters from both part of the equal sign must be percent encoded as defined by the standard https://www.w3.org/TR/html401/interact/forms.html.

Product Domain

Each Connector is assigned a unique API domain for devices to connect to. In this document, we will use the example domain of ".m2.connect.westpharma.com" as an example Product domain. Replace the example domain with the Endpoint shown in the associated Product page of your account UI.

TLS Connection Requirements

When making a secure TLS connection attempt to the API domain, it is required to specify the domain as the SNI field in the TLS connection request. The HTTP "Host" header must also be set to the domain name. Any mismatch or use of an invalid domain will result in the connection being terminated without response. Also read the West Connectivity connectivity TLS Specs..

Bandwidth considerations

TLS handshake has a significant request size and latency overhead for small HTTP payloads. This is because the server needs to provide the certificate chain (typically 3~4kb) to the device for verification. HTTP keep-alive can be used to mitigate most of the TLS overhead, especially when a device sends multiple small requests.

From our tests, sending three sequential write requests (single resource) without HTTP keep-alive used ~16kb bandwidth. The same requests with HTTP keep-alive enabled, over a single connection, used ~6kb bandwidth and had %40 lower latency.

Restrictions

There is no specific bandwidth or message size limitation, however each individual resource size MUST respect the maximum size of 1048576 bytes.

Authentication

A device may authenticate with a TLS Client Certificate, by using a secret Token specified in the "Authorization: Token" HTTP request header or by using a Password specified in the "Authorization: Basic" HTTP request header.

Examples:

{ Authorization: Token <token> } 
{ Authorization: Basic <base64-encoding of identity:password> }

West Connectivity Connector can be configured to allow devices to provision their own identities or to allow only whitelisted device identities to be provisioned. This configuration option is available via the Connector Settings tab as the Allow devices to register their own identity checkbox. When checked (default), any device using this API with the assigned Connector Domain can provision themselves without the need to be whitelisted in advance. If this option is disabled (unchecked), then device identities must be whitelisted in advance in order to provision and communicate with the Connector.

Note

When using a TLS Client Certificate for authentication, the certificate "Subject" CommonName (CN) must hold the connecting device's identity.

Device Provisioning

For device connection, activation of secure HTTP (HTTPS) is required. Typically, installation of the West Connectivity Root Server CA is not needed. However, should connection issues arise, please download and install the CA as a troubleshooting measure.

Provision

When a Product is configured for Token authentication, calling this endpoint will provision credentials for the given <identity> and return the secret <token> that the device must use for all subsequent API requests. Identities must also conform to the identity format specification defined in the Settings tab of the Product UI.

When a Product is configured for Password authentication, calling this endpoint will provision credentials for the given <identity> and <password> (at least 20 characters) that the device must use for all subsequent API requests. Identities must also conform to the identity format specification defined in the Settings tab of the Product UI.

When a Product is configured for Certificate authentication, provisioning will happen automatically when the device first connects. The request the device will make on its initial connection, is irrelevant and is not part of the provisioning process. That said, the initial connection results in two subsequent steps but separate operations:

provisioning,
the actual request.

The following behavior can be observed:

If step 1 fails, the connection will be terminated and step 2 will not be attempted.
If step 1 succeeds, step 2 will be attempted which may still fail. The response will depend on the outcome of step 2.
If the request is made to the "activate" (described below) endpoint, it will act as a re-provisioning request since provisioning will already have happened automatically.

Note

After that, the device must use the provisioned credentials to authenticate all subsequent API requests (e.g., read, write and ...).

The request takes the following form. The Content-Type and body will depend on the type of authentication being provisioned.

Token auth

POST /provision/activate HTTP/1.1
Host: <PRODUCT_ID>.m2.connect.westpharma.com
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Content-Length: <length>

id=<identity>

Response

HTTP/1.1 200 OK
Date: <date>
Server: Platform
Connection: Keep-Alive
Content-Length: <length>
Content-Type: text/plain; charset=utf-8

<token>

The response should return a 40-character string token.

Password auth

POST /provision/activate HTTP/1.1
Host: <PRODUCT_ID>.m2.connect.westpharma.com
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Content-Length: <length>

id=<identity>
password=<password>

Response

HTTP/1.1 204 OK
Date: <date>
Server: Platform
Connection: Keep-Alive

example

Provision identity 12345678

$ curl -i 'https://<PRODUCT_ID>.m2.connect.westpharma.com/provision/activate' \
    -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
    -d 'id=12345678'

Or in python:

import json
import requests

requests.post(
  f"https://<PRODUCT_ID>.m2.connect.westpharma.com/provision/activate",
  headers={ "Content-Type": "application/x-www-form-urlencoded; charset=utf-8" },
  data={ "id": "12345678" }
)

Response

HTTP/1.1 200 OK
Date: Fri, 05 May 2017 00:11:22 GMT
Server: Platform
Connection: Keep-Alive
Content-Length: 40
Content-Type: text/plain; charset=utf-8

22596363b3de40b06f981fb85d82312e8c0ed511

Response may also be:

HTTP/1.1 404 Not Found if whitelisting is required and the <identity> is not whitelisted.
HTTP/1.1 409 Conflict if the <identity> has already been provisioned.
HTTP/1.1 415 Unsupported Media Type if the <password> less than 20 characters.
See HTTP Responses for a full list of responses

One activated a devices will be visible on the West Connectivity Connector devices page with its IP set.

Reprovision

The idea of reprovisioning is that, in case device credentials get compromised or for other reasons, new credentials need to be set for a device already existing in the database. The reprovisioning process is the same as provisioning but requires that the device authenticate first. So the "activate" endpoint described above is called the same way but with authentication credentials provided in the call. That said, for certificate authentication, re-provisioning takes a slightly different form in that the new certificate must be sent in the payload, as follows:

Certificate auth

POST /provision/activate HTTP/1.1
Host: <PRODUCT_ID>.m2.connect.westpharma.com
Content-Type: application/x-pem-file; charset=utf-8
Content-Length: <length>

<certificate in PEM format>

Response

HTTP/1.1 204 OK
Date: <date>
Server: Platform
Connection: Keep-Alive

Static Content Files

This chapter explain how to interact with static files provided by the Content micro-service.

List Available Content

List available content <content-id>.

GET /api:v1/content/download HTTP/1.1
Host: <PRODUCT_ID>.m2.connect.westpharma.com
{Authorization: Token <token>}
{Authorization: Basic <base64-encoding of identity:password>}
<blank line>

Response

HTTP/1.1 200 OK
Date: <date>
Content-Length: <length>
Content-Type: text/csv; charset=utf-8

<content-id 1>
<content-id 2...>
<content-id n>

Response may also be:

See HTTP Responses for a full list of responses

Example

$ curl --location --request GET 'https://n4eu9chmttki00000.m2.connect.westpharma.com/api:v1/content/download' \
--header 'Authorization: Token fa92a8b9c854c2a5cbdaed18d716d503c7184a79'

HTTP/1.1 200 OK
Date: Tue, 31 Jan 2023 09:53:35 GMT
Content-Length: 52
Content-Type: text/csv; charset=utf-8

device2/test2/test.png
device2/test2/lean.pdf

Get Content Info

Retrieve meta information (content-type, size, updated timestamp, description) for the specified <content-id>.

GET /api:v1/content/download?id=<content-id>&info HTTP/1.1
Host: <PRODUCT_ID>.m2.connect.westpharma.com
{Authorization: Token <token>}
{Authorization: Basic <base64-encoding of identity:password>}
<blank line>

Response

HTTP/1.1 200 OK
Date: <date>
Content-Length: <number of bytes being returned>
Content-Type: <content-type>

<Content-Type>,<Content-Length>,<Content-Upload-Timestamp>,

Response may also be:

See HTTP Responses for a full list of responses

Example

$ curl --location --request GET 'https://n4eu9chmttki00000.m2.connect.westpharma.com/api:v1/content/download?id=device2/test2/test.png&info' \
--header 'Authorization: Token fa92a8b9c854c2a5cbdaed18d716d503c7184a79'

HTTP/1.1 200 OK
Date: Mon, 30 Jan 2023 07:51:19 GMT
Content-Type: image/png

image/png,1557,1675065374,

Download Content

Download the content <content-id> in full or in part. To request chunks of the content, use the header Range: bytes=<range-specifier>. <range-specifier> takes the form of X-Y where both X and Y are optional but at least one of them must be present. X is the start byte position to return. Y is the end position. Both are 0 based. If X is omitted, Y will request the last Y count of bytes of the content. If Y is omitted, it will default to the end of the content. The response Content-Type header will be as defined in the content meta info.

Download full or partial content directly

Note

Content items must be less than 20 MB in size.

GET /api:v1/content/download?id=<content-id> HTTP/1.1
Host: <PRODUCT_ID>.m2.connect.westpharma.com
{Authorization: Token <token>}
{Authorization: Basic <base64-encoding of identity:password>}
{Range: bytes=<range-specifier>}
<blank line>

Response

HTTP/1.1 200 OK
Date: <date>
Content-Length: <number of bytes being returned>
Content-Type: <content-type>
{Accept-Ranges: bytes}
{Content-Range: bytes <first position>-<last position>/<total length>}

<blob>

Response may also be:

HTTP/1.1 206 Partial Content if the response is partial.
See HTTP Responses for a full list of responses

Examples

Download entire content

$ curl --location --request GET 'https://n4eu9chmttki00000.m2.connect.westpharma.com/api:v1/content/download?id=device2/test2/test.png' \
--header 'Authorization: Token fa92a8b9c854c2a5cbdaed18d716d503c7184a79' --output test.png

HTTP/1.1 200 OK
Date: Mon, 30 Jan 2023 07:51:19 GMT
Content-Length: 1557
Content-Type: image/png

<1557-byte-blob>

Download first 1024 bytes of the content

$ curl --location --request GET 'https://n4eu9chmttki00000.m2.connect.westpharma.com/api:v1/content/download?id=device2/test2/test.png' --header 'Authorization: Token fa92a8b9c854c2a5cbdaed18d716d503c7184a79' --header 'Range: bytes=0-1023' --output partial_test.png

HTTP/1.1 206 Partial Content
Date: Mon, 30 Jan 2023 07:59:45 GMT
Content-Length: 1024
Content-Type: image/png
Accept-Ranges: bytes
Content-Range: bytes 0-1023/1557

<1024-byte-blob>

Download large content by URL

Note

Content items must be less than 512 MB in size.

Get url for downloading

GET /api:v1/content/download?id=<content-id>&url&{expires_in=seconds} HTTP/1.1
Host: <PRODUCT_ID>.m2.connect.westpharma.com
{Authorization: Token <token>}
{Authorization: Basic <base64-encoding of identity:password>}
<blank line>

expires_in is a optional argument, the defualt available time of url is 300 seconds, please set expires_in=3600 if the required available time of url is 1 hour.

Response

HTTP/1.1 200 OK
Date: <date>
Content-Length: <number of bytes being returned>
Content-Type: <content-type>

<url>

The in body is an endpoint for file downloading.

Get content by requesting url

GET <url> HTTP/1.1

Response

HTTP/1.1 200 OK
Date: <date>
Content-Length: <number of bytes being returned>
Content-Type: <content-type>


<File bytes>

Example

Get content url:

$ curl --location --request GET 'https://n4eu9chmttki00000.m2.connect.westpharma.com/api:v1/content/download?id=device2/test2/test.png&url' \
--header 'Authorization: Token fa92a8b9c854c2a5cbdaed18d716d503c7184a79'

HTTP/1.1 200 OK
Date: Mon, 30 Jan 2023 09:08:28 GMT
Content-Length: 281
Content-Type: text/plain

https://storage.hosted.diagnostic.westpharma.com/dev-content-service/n4eu9chmttki00000/device2/test2/test.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=muranodev%2F20230130%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230130T090829Z&X-Amz-Expires=300&X-Amz-SignedHeaders=host&X-Amz-Signature=7ef14ae4245410efde8525c798099e1aaf0194e43f9e29f120bfacecda7ff545

Get entire content by requesting url and save the file as output.png:

$ curl --location --request GET 'https://storage.hosted.diagnostic.westpharma.com/dev-content-service/n4eu9chmttki00000/device2/test2/test.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=muranodev%2F20230130%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230130T090829Z&X-Amz-Expires=300&X-Amz-SignedHeaders=host&X-Amz-Signature=7ef14ae4245410efde8525c798099e1aaf0194e43f9e29f120bfacecda7ff545' -o output.png

In other languages:

Please contact our support team for sample code.

Upload Content

The device API provides the ability to upload files from the device into West Connectivity Content Store. Uploaded files will be accessible on the Content Service under the device2/<device identity-id>/ folder. Files uploaded by a given device will be available for download to that device only and will not be available to other devices. This method generates an event type of "content_in" on the West Connectivity Device2 service. It carries all the meta information about the uploaded content but not the actual content blob. See the device2 service reference.

Upload small-size content

Note

Content items must be less than 20 MB in size.

POST /api:v1/content/upload/<content-id> HTTP/1.1
Host: <product>.m2.connect.westpharma.com
{Authorization: Token <token>}
{Authorization: Basic <base64-encoding of identity:password>}
Content-Length: <length in bytes>
{Content-Type: <media type of file>}

<content body payload>

Response

HTTP/1.1 204 No Content
Date: <date>

Example

$ curl --location --request POST 'https://n4eu9chmttki00000.m2.connect.westpharma.com/api:v1/content/upload/test.png' \
--header 'Authorization: Token fa92a8b9c854c2a5cbdaed18d716d503c7184a79' \
--header 'Content-Type: image/png' \
--data-binary '@/C:/Users/test/test.png'

HTTP/1.1 204 No Content
Date: Mon, 30 Jan 2023 10:03:09 GMT

Or other languages:

Please contact our support team for sample code.

Upload large-size content by URL

Note

Content items must be less than 512 MB in size.

Get URL for content uploading

GET /api:v1/content/upload/<content-id>?{type=content-type}&{expires_in=seconds} HTTP/1.1
Host: <product>.m2.connect.westpharma.com
{Authorization: Token <token>}
{Authorization: Basic <base64-encoding of identity:password>}
Content-Length: <length in bytes>
{Content-Type: <media type of file>}

<content body payload>

expires_in is a optional argument, the defualt available time of url is 300 seconds, please set expires_in=3600 if the required available time of url is 1 hour.

type is a optional argument, please set it according to the content-type of content. (eg. type=image/png)

Response

HTTP/1.1 204 No Content
Date: <date>

<body with url>

For the details of reponse body, could see below examples.

Examples

Get URL for content uploading:

curl --location --request GET 'https://n4eu9chmttki00000.m2.connect.westpharma.com/api:v1/content/upload/test.png?type=image/png' \
--header 'Authorization: Token fa92a8b9c854c2a5cbdaed18d716d503c7184a79'

{
    "url": "https://storage.hosted.diagnostic.westpharma.com:443/dev-content-service",
    "method": "POST",
    "inputs": {
        "x-amz-signature": "c63960aa5c56a5b006277747cc753d729c9be79c18ac945abb22d012ec953be8",
        "x-amz-date": "20230131T022610Z",
        "x-amz-credential": "muranodev/20230131/us-west-2/s3/aws4_request",
        "x-amz-algorithm": "AWS4-HMAC-SHA256",
        "policy": "eyJleHBpcmF0aW9uIjoiMjAyMy0wMS0zMVQwMjozMToxMC4wMDBaIiwiY29uZGl0aW9ucyI6W3siY29udGVudC10eXBlIjoiaW1hZ2UvcG5nIn0sWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsMCw1MzY4NzA5MTJdLHsieC1hbXotZGF0ZSI6IjIwMjMwMTMxVDAyMjYxMFoifSx7IngtYW16LWNyZWRlbnRpYWwiOiJtdXJhbm9kZXYvMjAyMzAxMzEvdXMtd2VzdC0yL3MzL2F3czRfcmVxdWVzdCJ9LHsieC1hbXotYWxnb3JpdGhtIjoiQVdTNC1ITUFDLVNIQTI1NiJ9LHsiYWNsIjoiYXV0aGVudGljYXRlZC1yZWFkIn0seyJrZXkiOiJuNGV1OWNobXR0a2kwMDAwMC9kZXZpY2UyL3Rlc3QyL3Rlc3QucG5nIn0seyJidWNrZXQiOiJkZXYtY29udGVudC1zZXJ2aWNlIn1dfQ==",
        "key": "n4eu9chmttki00000/device2/test2/test.png",
        "content-type": "image/png",
        "acl": "authenticated-read"
    },
    "id": "device2/test2/test.png",
    "field": "file",
    "enctype": "multipart/form-data"
}

Note

The value of url will be used on content uploading, the value of inputs will be used on making form-data, please see below example for more details

Upload content :

curl --location --request POST 'https://storage.hosted.diagnostic.westpharma.com:443/dev-content-service' \
--form 'x-amz-signature="c63960aa5c56a5b006277747cc753d729c9be79c18ac945abb22d012ec953be8"' \
--form 'x-amz-date="20230131T022610Z"' \
--form 'x-amz-credential="muranodev/20230131/us-west-2/s3/aws4_request"' \
--form 'x-amz-algorithm="AWS4-HMAC-SHA256"' \
--form 'policy="eyJleHBpcmF0aW9uIjoiMjAyMy0wMS0zMVQwMjozMToxMC4wMDBaIiwiY29uZGl0aW9ucyI6W3siY29udGVudC10eXBlIjoiaW1hZ2UvcG5nIn0sWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsMCw1MzY4NzA5MTJdLHsieC1hbXotZGF0ZSI6IjIwMjMwMTMxVDAyMjYxMFoifSx7IngtYW16LWNyZWRlbnRpYWwiOiJtdXJhbm9kZXYvMjAyMzAxMzEvdXMtd2VzdC0yL3MzL2F3czRfcmVxdWVzdCJ9LHsieC1hbXotYWxnb3JpdGhtIjoiQVdTNC1ITUFDLVNIQTI1NiJ9LHsiYWNsIjoiYXV0aGVudGljYXRlZC1yZWFkIn0seyJrZXkiOiJuNGV1OWNobXR0a2kwMDAwMC9kZXZpY2UyL3Rlc3QyL3Rlc3QucG5nIn0seyJidWNrZXQiOiJkZXYtY29udGVudC1zZXJ2aWNlIn1dfQ=="' \
--form 'key="n4eu9chmttki00000/device2/test2/test.png"' \
--form 'content-type="image/png"' \
--form 'acl="authenticated-read"' \
--form 'file=@"/C:/Users/test/test.png"'

HTTP/1.1 204 No Content
Date: Tue, 31 Jan 2023 02:27:01 GMT

Writing And Reading Data

Write

Write one or more resources identified by <alias> with the given <value>. The connecting device is identified and authenticated with the provided <token>, <password> or <certificate>. If the West Connectivity Connector has defined resources with matching <alias>es, the <value>s are stored as the device state at timestamp the data was received by West Connectivity. If multiple aliases are specified, they are written at the same timestamp. This method generates an event type of "data_in" on the West Connectivity Device2 service and may be used to, for instance, store the data in the Tsdb database or alert users or other services of the event.

request

POST /api:v1/stack/alias HTTP/1.1
Host: <PRODUCT_ID>.m2.connect.westpharma.com
{Authorization: Token <token>}
{Authorization: Basic <base64-encoding of identity:password>}
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Content-Length: <length>
<blank line>
<alias 1>=<value 1>&<alias 2...>=<value 2...>&<alias n>=<value n>

Response

HTTP/1.1 204 No Content
Date: <date> 
Server: Platform
Connection: Keep-Alive
<blank line>

See HTTP Responses for a full list of responses.

Example

$ curl -i 'https://<PRODUCT_ID>.m2.connect.westpharma.com/api:v1/stack/alias' \
    -H 'Authorization: Token 22596363b3de40b06f981fb85d82312e8c0ed511' \
    -d 'temperature=63'

Or in python:

import json
import requests

requests.post(
  f"https://<PRODUCT_ID>.m2.connect.westpharma.com/api:v1/stack/alias",
  headers={
    "Content-Type": "application/x-www-form-urlencoded; charset=utf-8",
    "Authorization": "Token <token>"
  },
  data={
    "temperature": 63,
    "data_in": json.dumps({ "jsondata": 42 })
  }
)

Response

HTTP/1.1 204 No Content
Date: Fri, 05 May 2017 00:11:22 GMT
Server: Platform
Connection: Keep-Alive

Write with timestamp

Write ONE resource identified by <alias> with the given <value> and <timestamp>. The connecting device is identified and authenticated with the provided <token>, <password> or <certificate>. If the West Connectivity Connector has defined resources with matching <alias>, the <value>s are stored as the device state at <timestamp> provided by requester.

request

POST /api:v1/stack/alias/<alias> HTTP/1.1
Host: <PRODUCT_ID>.m2.connect.westpharma.com
{Authorization: Token <token>}
{Authorization: Basic <base64-encoding of identity:password>}
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Content-Length: <length>
<blank line>
<timestamp 1>=<value 1>&<timestamp 2...>=<value 2...>&<timestamp n>=<value n>

Response

HTTP/1.1 204 No Content
Date: <date> 
Server: Platform
Connection: Keep-Alive
<blank line>

Example

$ curl -i 'https://<PRODUCT_ID>.m2.connect.westpharma.com/api:v1/stack/alias/temperature' \
    -H 'Authorization: Token 22596363b3de40b06f981fb85d82312e8c0ed511' \
    -d '1715654776=23'
    -d '1715654777=24'

Write as target device

In the event that an identified and authenticated device is available to serve as a gateway device, write ONE resource identified by <alias> with the specified <timestamp> and <value>. This gateway device will receive published data and forward it to the target device. The connecting gateway device is identified and authenticated with the provided <token>, <password> or <certificate>. If the West Connectivity Connector has defined resources with matching <alias>, the <value>s are stored as the target device state at <timestamp> the provided by requester.

Note

Please ensure that the target device's permissions are set to allow the gateway device to forward data to it.

request

POST /api:v1/stack/alias/as/<Target_Device_Name>/<alias> HTTP/1.1
Host: <PRODUCT_ID>.m2.connect.westpharma.com
{Authorization: Token <token>}
{Authorization: Basic <base64-encoding of identity:password>}
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Content-Length: <length>
<blank line>
<timestamp>=<value>

Response

HTTP/1.1 204 No Content
Date: <date> 
Server: Platform
Connection: Keep-Alive
<blank line>

Example

$ curl -i 'https://<PRODUCT_ID>.m2.connect.westpharma.com/api:v1/stack/alias/as/target/temperature' \
    -H 'Authorization: Token 22596363b3de40b06f981fb85d82312e8c0ed511' \
    -d '1715654776=23'

Read for latest data

Read the latest value from one or more resources. If at least one <alias> resource definition exists, the set value will be returned.

Read the latest value from one or more resources with <alias>. The client (e.g., device or portal) to read from is identified by <token>, <password> or <certificate>. If at least one <alias> is found and has data, data will be returned.

Request

GET /api:v1/stack/alias?<alias 1>&<alias 2...>&<alias n> HTTP/1.1
Host: <PRODUCT_ID>.m2.connect.westpharma.com
{Authorization: Token <token>}
{Authorization: Basic <base64-encoding of identity:password>}
Accept: application/x-www-form-urlencoded; charset=utf-8
<blank line>

Response

HTTP/1.1 200 OK
Date: <date>
Server: Platform
Connection: Close
Content-Length: <length>
<blank line>
<alias 1>=<value 1>&<alias 2...>=<value 2...>&<alias n>=<value n>

Response may also be HTTP/1.1 204 No Content if either none of the aliases are found or the device state for the given aliases are empty
See HTTP Responses for a full list of responses

Example

$ curl -i 'https://<PRODUCT_ID>.m2.connect.westpharma.com/api:v1/stack/alias?thermostat' \
    -H 'Authorization: Token 22596363b3de40b06f981fb85d82312e8c0ed511' \
    -H 'Accept: application/x-www-form-urlencoded; charset=utf-8'

HTTP/1.1 200 OK
Date: Fri, 05 May 2017 00:11:22 GMT
Server: Platform
Connection: Keep-Alive
Content-Length: 13
Content-Type: application/x-www-form-urlencoded; charset=utf-8

thermostat=65

Read as Target device

Read the data with reported/inserted timestamp from one or more resources or signals of ONE target device with <alias> from gateway device. The client (e.g., device or portal) to read from is identified by gateway device's <token>, <password> or <certificate>. If at least one <alias> is found and has data, data will be returned.

Note

Please ensure that the gateway device's permission is set to allow the the topic rs/<target-device-id>/*, e.g. rs/testdevice/*.

Request

GET /api:v1/query?identity=<gateway-device-id>&signals=<resource/signal alias 1>,<resource/signal alias 2>,<resource/signal alias 3>...&start_time=<start timestamp>&end_time=<end timestamp> HTTP/1.1
Host: <PRODUCT_ID>.m2.connect.westpharma.com
{Authorization: Token <gateway-identity token>}
{Authorization: Basic <base64-encoding of gateway-identity:password>}
Accept: application/x-www-form-urlencoded; charset=utf-8
<blank line>

Parameters:

Name	Type	Description
identity	string	The device name
signals	string	A list of signals(include both resource and config_io signals) to query, concatenated with ','. For example, 'signal1,signal2,signal3'
start_time	integer	The start of time range to filter data. Formatted as UNIX timestamp with fraction digits representing millisecond and microsecond. The precision is specified by epoch parameter.
end_time	integer	The end of time range to filter data. Formatted as UNIX timestamp with fraction digits representing millisecond and microsecond. The precision is specified by epoch parameter.
limit	integer	The number of items to return, if there are datas with duplicate ts the return datas might be fewer than limit
order	string	The order of data sort by reported time[desc, asc]
epoch	string	The unix timestamp precision[s, ms, us]

Response

HTTP/1.1 200 OK
Date: <date>
Server: Platform
Connection: Close
Content-Length: <length>
<blank line>
<json object>

Response may be HTTP/1.1 400 Bad Request if the allowed topic of gateway device's permission hasn't been set.
See HTTP Responses for a full list of responses

Example

 Date: Server: Connection: Content-Length: Content-Type:  {                           

href="#__codelineno-58-1">$ curl -i 'https://<PRODUCT_ID>.m2.connect.westpharma.com/api:v1/query?identity=device9&signals=temperature%2CBatch_ID&start_time=1725612590&end_time=1725870567' \ class="w">    -H 'Authorization: Token 22596363b3de40b06f981fb85d82312e8c0ed511' \ class="w">    -H 'Accept: application/x-www-form-urlencoded; charset=utf-8' href="#__codelineno-59-1">HTTP/1.1 200 OK Fri, 05 May 2017 00:11:22 GMT Platform Keep-Alive 13 application/x-www-form-urlencoded; charset=utf-8 "data": { "device9/data_in/Batch_ID": [ { "inserted_time": 1725615295.0, "reported_time": 1725615294.0, "value": "1202156" } ], "device9/resource/temperature": [ { "inserted_time": 1725615263.0, "reported_time": 1725615263.0, "value": 38 } ] }, "has_next": false, "next_start_time": 1725615294.0, "q": { "end_time": "1725870567", "identity": "device9", "signals": "temperature,Batch_ID", "start_time": "1725612590" }, "total": 2 }

Read as Target device for Latest data
Read the latest value from one or more resources or signals of ONE target device with <alias> from gateway device. The client (e.g., device or portal) to read from is identified by gateway device's <token>, <password> or <certificate>. If at least one <alias> is found and has data, data will be returned.

Note
Please ensure that the gateway device's permission is set to allow the the topic rs/<target-device-id>/*, e.g. rs/testdevice/*.

Request
GET /api:v1/latest-value?identity=<gateway-device-id>&signals=<resource/signal alias 1>,<resource/signal alias 2>,<resource/signal alias 3>... HTTP/1.1
Host: <PRODUCT_ID>.m2.connect.westpharma.com
{Authorization: Token <gateway-identity token>}
{Authorization: Basic <base64-encoding of gateway-identity:password>}
Accept: application/x-www-form-urlencoded; charset=utf-8
<blank line>

Parameters:



Name
Type
Description




identity
string
The device name


signals
string
A list of signals(include both resource and config_io signals) to query, concatenated with ','. For example, 'signal1,signal2,signal3'


limit
integer
The number of items to return, if there are datas with duplicate ts the return datas might be fewer than limit


order
string
The order of data sort by reported time[desc, asc]


page
integer
The pagination number



Response
HTTP/1.1 200 OK
Date: <date>
Server: Platform
Connection: Close
Content-Length: <length>
<blank line>
<json object>


Response may be HTTP/1.1 400 Bad Request if the allowed topic of gateway device's permission hasn't been set.
See HTTP Responses for a full list of responses

Example
$ curl -i 'https://<PRODUCT_ID>.m2.connect.westpharma.com/api:v1/latest-value?identity=device3&signals=temperature%2CBatch_ID' \
    -H 'Authorization: Token 22596363b3de40b06f981fb85d82312e8c0ed511' \
    -H 'Accept: application/x-www-form-urlencoded; charset=utf-8'

HTTP/1.1 200 OK
Date: Fri, 05 May 2017 00:11:22 GMT
Server: Platform
Connection: Keep-Alive
Content-Length: 13
Content-Type: application/x-www-form-urlencoded; charset=utf-8

{
    "data": [
        {
            "resource": "data_in",
            "identity": "device3",
            "last_value": "1202156",
            "last_insert": "2024-09-06 08:30:59.432002Z",
            "last_update": "2024-09-06 08:30:59.298489Z",
            "signal_name": "Batch_ID"
        },
        {
            "resource": "temperature",
            "identity": "device3",
            "last_value": 22,
            "last_insert": "2024-09-06 07:13:32.018000Z",
            "last_update": "2024-09-06 07:13:31.913369Z",
            "signal_name": "temperature"
        }
    ],
    "q": {
        "identity": "device3",
        "limit": 100,
        "order": "asc",
        "page": 1,
        "signals": "temperature,Batch_ID"
    },
    "total": 2
}


Hybrid Read Write
Write one or more values with <alias w> with given <value> and also read the most recent values from <alias r>.

Note
All writes occur before all reads.

Request
POST /api:v1/stack/alias?<alias r1>&<alias r2...>&<alias rn> HTTP/1.1
Host: <PRODUCT_ID>.m2.connect.westpharma.com
{Authorization: Token <token>}
{Authorization: Basic <base64-encoding of identity:password>}
Accept: application/x-www-form-urlencoded; charset=utf-8
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Content-Length: <length>
<blank line>
<alias w1>=<value 1>&<alias w2...>=<value 2...>&<alias wn>=<value n>

Response
HTTP/1.1 200 OK
Date: <date>
Server: Platform
Connection: Close
Content-Length: <length>
<blank line>
<alias r1>=<value 1>&<alias r2...>=<value 2...>&<alias rn>=<value n>


Response may also be HTTP/1.1 204 No Content if either none of the aliases are found or the device state for the given aliases are empty
See HTTP Responses for a full list of responses

Example
$ curl https://<PRODUCT_ID>.m2.connect.westpharma.com/api:v1/stack/alias?thermostat \
    -H 'Authorization: Token 22596363b3de40b06f981fb85d82312e8c0ed511' \
    -H 'Accept: application/x-www-form-urlencoded; charset=utf-8' \
    -d 'temperature=63'

HTTP/1.1 200 OK
Date: Fri, 05 May 2017 00:11:22 GMT
Server: Platform
Connection: Keep-Alive
Content-Length: 13
Content-Type: application/x-www-form-urlencoded; charset=utf-8

thermostat=65


Long Polling
The read endpoint also supports long polling. Long polling is a method of getting a server push without the complexities of setting up publicly accessible HTTP server endpoints on your device. As the name suggests, long polling is similar to normal polling of an HTTP resource, but instead of requiring the client to make a new request to the server constantly, the server will wait to return until it has new information to return to the client (or a timeout has been reached).
To perform a request with long polling, simply add the header Request-Timeout: <milliseconds> to your request. The server will then wait until a new datapoint is written to the given resource and will then immediately return the value. If no datapoint is written before that time, a 304 Not Modified is returned and the client may make another long polling request to continue monitoring that resource.
You may also optionally add an If-Modified-Since header to specify a start time to wait. This is exactly the same as the alias.last semantics in scripting. You will want to use this if it's important that you receive all updates to a given resource; otherwise it is possible to miss points written between long polling requests.

Note
Only one resource may be read at a time when using long polling.

Request
GET /api:v1/stack/alias?<alias 1> HTTP/1.1
Host: <PRODUCT_ID>.m2.connect.westpharma.com
{Authorization: Token <token>}
{Authorization: Basic <base64-encoding of identity:password>}
Accept: application/x-www-form-urlencoded; charset=utf-8
Request-Timeout: <timeout>
If-Modified-Since: <timestamp>
<blank line>


<alias> is the alias you monitor for new datapoints.
Request-Timeout specifies how long to wait on changes. <timeout> is a millisecond value and cannot be more than 300 seconds (300,000 ms).
If-Modified-Since specifies waiting on aliases since the <timestamp>. <timestamp> can be timestamp seconds since 1970-01-01 00:00:00 UTC or standard HTTP-Date format. If this is not specified, it defaults to "now."

Response
When the device set state is updated:
HTTP/1.1 200 OK
Date: <date>
Server: Platform
Connection: Close
Content-Length: <length>
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Last-Modified: <value-set-date>
<blank line>
<alias>=<value>

If the device state is not updated before timeout:
HTTP/1.1 304 Not Modified
Date: <date>
Server: Platform
Connection: Close
Content-Length: <length>
<blank line>

When the resource is written and a value is returned, a Last-Modified header is included. When it is vital for your application to receive all updates to a resource, you can pass the Last-Modified header value back as the If-Not-Modified-Since header in your next request to make sure you do not miss any points that may have been written since the last request returned.
Example
$ curl https://<PRODUCT_ID>.m2.connect.westpharma.com/api:v1/stack/alias?thermostat \
    -H 'Authorization: Token 22596363b3de40b06f981fb85d82312e8c0ed511' \
    -H 'Accept: application/x-www-form-urlencoded; charset=utf-8'
    -H 'Request-Timeout: 30000
    -H 'If-Modified-Since: 1408088308

HTTP/1.1 200 OK
Date: Fri, 05 May 2017 00:11:22 GMT
Server: Platform
Connection: Keep-Alive
Content-Length: 13
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Last-Modified: 1408088412

thermostat=65


Record
Report data to one or more historical timestamps of one or more aliases. If the West Connectivity Connector has defined resources with matching <alias>es, the most recent <value>s are stored as the device state with the timestamp the data was received by West Connectivity. The connecting device is identified and authenticated with the provided <token>. Timestamp support floating-point based on seconds and interpret to microseconds.
Example:
timestamp1=1551674686.339 s -> 1551674686339000 us
timestamp2=1551674686.339876 s -> 1551674686339876 us

Acceptable values for timestamps are as follows:

when positive, the value is the number of seconds since 1970.01.01 00:00:00 UTC.
when negative, the value is a time offset in seconds relative to 'now'. For example, -3600 means one hour ago.

Request
This example records to <alias 1> in <timestamp 1> and <timestamp 2>, and records to <alias 2> in <timestamp 3> and <timestamp 4>.
POST /api:v1/stack/record HTTP/1.1
Host: <PRODUCT_ID>.m2.connect.westpharma.com
{Authorization: Token <token>}
{Authorization: Basic <base64-encoding of identity:password>}
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Content-Length: <length>
<blank line>
alias=<alias 1>&<timestamp 1>=<value 1>&<timestamp 2>=<value 2>&alias=<alias 2>&<timestamp 3>=<value 3>&<timestamp 4>=<value 4>

Response
HTTP/1.1 204 No Content 
Date: <date> 
Server: <server> 
Connection: Close 
Content-Length: 0 
<blank line>



See HTTP Responses for a full list of responses.


If <timestamp 1> and <timestamp 2>, <timestamp 3> and <timestamp 4> have less than one-second difference:


HTTP/1.1 409 Conflict
Date: <date>
Server: <server>
Connection: Close
Content-Length: <length>
<alias 1>=<timestamp 1>&<alias 2>=<timestamp 3>

Example
Report two values to temperature and three to state.
$ curl https://<PRODUCT_ID>.m2.connect.westpharma.com/api:v1/stack/record \
    -H 'Authorization: Token XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
    -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
    -d 'alias=temperature&1506708552.123=23&1506708551=22&alias=state&1506708552=on&1506708551=off&1506708550.123456=on'


Other
Timestamp
Get the current time according to the server.
Request
GET /timestamp HTTP/1.1
Host: <PRODUCT_ID>.m2.connect.westpharma.com
<blank line>

Response
HTTP/1.1 200 OK
Date: <date>
Server: Platform
Connection: Keep-Alive
Content-Length: <length>
Content-Type: text/plain; charset=utf-8

<timestamp>

* See HTTP Responses for a full list of responses
Example
$ curl -i https://<PRODUCT_ID>.m2.connect.westpharma.com/timestamp

HTTP/1.1 200 OK
Date: Fri, 05 May 2017 00:11:22 GMT
Server: Platform
Connection: Keep-Alive
Content-Length: 10
Content-Type: text/plain; charset=utf-8

1408088308










  



  
    
      
        Was this page helpful?
      
      
        
          
            
          
            
          
        
        
          
            
              
              
                
              
              Thanks for your feedback!
            
          
            
              
              
                
              
              Thanks for your feedback!