Platform Of Trust Translator API documentation version v1

http://{base_url}/{version}

  • base_url: required (string)
  • version: required (v1)

/health

API Health endpoints

get

get

Health check endpoint

/fetch

Fetch data from data source

post

post

Get the data for the translator

Get the data for the translator

Headers

  • X-PoT-Signature: required (string)

    A HMAC-RSA256 generated signature of the payload. E.g. HMAC-RSA256(,)

    Example:

    jxj28KTspn2DR4ryIX4YzSqKz9IEQuYQGw9LpRK5ydg=
  • X-PoT-Token: (string)

    The user's OAuth token

    Example:

    ryIX4YzSqKz9I
  • X-PoT-App: (string)

    App ID

    Example:

    e73c3e11-1500-4fb6-854d-07806724ce0f

Body

Media type: application/json

Type: object

Properties
  • timestamp: required (datetime)

    The timestamp when the request was sent. RFC3339 format.

    Example:

    2018-11-22T10:00:00Z
  • productCode: required (string)

    The product code of the data product.

    Example:

    example-room-temperature
  • parameters: required (object)

    Optional additional parameters that the translator needs.

      Example:

      {
  "deviceId": "r_305_d_32"
}

    Example:

    {
  "timestamp": "2018-11-22T10:00:00Z",
  "productCode": "example-room-temperature",
  "parameters": {
    "deviceId": "r_305_d_32"
  }
}

    HTTP status code 200

    Body

    Media type: application/json

    Type: object

    Properties
    • @context: required (string)

      The URL to the context. Should match data product context.

      Example:

      https://example.org/contexts/room-temperature.jsonld
    • data: required (object)

      Any data returned from the source.

      Example:

      {
  "deviceId": "r_305_d_32",
  "temperature": {
    "service_type": "temperature",
    "unit_measurement": "Celsius",
    "value": "22.5"
  }
}
    • signature: required (object)

      Signature information. The signature is generated based on the data object with the created value added to the key __signed__. The __signed__ is NOT returned in the data, but MUST be added when validating the signature. The type MUST match one of the data product organizationPublicKeys[].type value and the creator MUST match one of the data product organizationPublicKeys[].url value.

      Example:

      {
  "type": "<should match organizationPublicKeys.type in data product>",
  "created": "<RFC3339 timestamp when data was fetched>",
  "creator": "<should match organizationPublicKeys.url in data product>",
  "signatureValue": "<the value of the signature>"
}

    Example:

    {
  "@context": "https://example.org/contexts/room-temperature.jsonld",
  "data": {
    "deviceId": "r_305_d_32",
      "temperature": {
        "service_type": "temperature",
        "unit_measurement": "Celsius",
        "value": "22.5"
      }
  },
  "signature": {
    "type": "RsaSignature2018",
    "created": "2018-11-22T12:00:00Z",
    "creator": "https://example.org/creator/public_key.pub",
    "signatureValue": "eyJ0eXAiOiJK...gFWFOEjXk"
  }
}

    HTTP status code 422

    Body

    Media type: application/json

    Type: any

    Examples:

    Signature validation failed:

    {
  "error": {
    "status": 422,
    "message": "Signature validation failed."
  }
}

    Missing required header:

    {
  "error": {
    "status": 422,
    "message": "Missing required header \"x-pot-signature\""
  }
}

    Missing required field:

    {
  "error": {
    "status": 422,
    "message": {
      "timestamp": [
        "Missing data for required field."
      ]
    }
  }
}