Pepperl-Fuchs

pepperl-fuchs_asi_3_gateway

PUBLIC | PUBLISHED

Pepperl+Fuchs ASi-3 Gateway

This OpenAPI specification describes the RESTful API endpoints for the Pepperl+Fuchs ASi-3 Gateway.

Introduction into RestAPI

  1. Learn about the Basics of the ASi KE5 Gateway, IIoT, and REST API

  2. Learn How to Interface the ASi KE5 Gateway via REST API and Postman

  3. Learn How to Interface the ASi KE5 Gateway via REST API and Node-RED

Authenticate: How It Works

In order to authenticate the RESTful API to the devices, a client has to handle JSON Web Tokens.
JWTs are used for a short-lived authentication between the client and the device.

What is JSON Web Token (JWT)?

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way
for securely transmitting information between parties as a JSON object.
This information can be verified and trusted because it is digitally signed.

What is the JSON Web Token structure?

A JSON Web Token (JWT) consists of 3 parts separated by a period (.). The header and the payload are
JSON objects that are serialized to UTF-8 bytes and then encoded using base64url encoding.

  • Header

  • Payload

  • Signature

As a result, a JWT typically takes the following form:

{base64url encoded header}.{base64url encoded payload}.{base64url encoded signature}

Header

The header consists of two parts: the type of the token, e.g. JWT, and the signing algorithm used, e.g. HMAC SHA256 or RSA.

For example:

{"alg" : "HS256", "typ" : "JWT"}

Payload

The second part of the JWT is the payload that contains the claims.
Claims are statements concerning an entity (typically, the user) and additional data.

Some frequently used typical standard claims are the following:

  • Subject (sub): The name of the authenticated subscriber

  • Issued at (iat): The timestamp at which the token was created

  • Expiration time (exp): The timestamp at which the token expires

A typical example for a payload is the following:

{"sub": "John Doe", "iat": 1584529761, "exp": 1584529821}

Signature

The signature is used to verify that the message has not been changed along the way.

In order to create the signature, sign the following parts of JWT information:

  • The base64UrlEncode(header)

  • The base64UrlEncode(payload)

For example, when using the HMAC SHA256 algorithm, the signature will be created in the following way:

HMACSHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload), 256-bit-secret )

Putting All Signature Parts Together

The resulting signature consists of three base64-url strings, each being separated by a period.

The following example shows a JWT with a header and a payload that were previously encoded
and signed with an API key secret.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJKb2huIERvZSIsImlhdCI6MTU4NDUyOTc2MSwiZXhwIjoxNTg0NTI5ODIxfQ.KzWoTnuto_VPtkYiOROyfZ80zL_tIY6eC4smVPjmtEs

How the Authentication Works

  • A client sends the user name/password combination to the server.

  • The server validates the authentication.

  • If the authentication is successful, the server creates a JWT.

  • If the authentication fails, the server issues an error message.

  • After an initial successful authentication, each further client request supplies the JWT in the following way.

Authorization: Bearer <jwt_token>

  • Upon receiving the JWT, the server validates the JWT and issues a confirmation message. If the JWT cannot be successfully validated, the server issues an error message.

Examples for using cURL

Use the Command-Line Tool (cURL) in order to Request the JWT

$ curl -H "Content-Type: application/json" --request POST 'http://192.168.0.2/api/auth/login' --data '{ "username":"admin", "password":"12341234" }'

{ "token": "<jwt_token>" }

Example for using with Python


import requests

import json


hostname = "http://<ipAddress>"

headersList = {
"Content-Type": "application/json" 
}


# Login


rsp = requests.post(
  hostname + "/api/auth/login",
  json={
    "username": "admin",
    "password": "ADMINADMIN"
  },
  headers=headersList,
  timeout=10)

token = rsp.json()['token']

headersList["Authorization"] = f"Bearer {token}"


# Get current ASi devices list from Line 1


rsp = requests.get(hostname + "/api/asi/lines/1", headers=headersList, timeout=10)

line_status = rsp.json()

print(line_status)

Changelog:

  • 1.1.0

    • Replaced process data for ASi line with better performance API
    • Extend process data for ASi line with filters parameter
    • Extend /system/time with NTP information
    • Add API for DHCP-Server configuration
    • Removed useless system capabilities

  • 1.0.1

    • Changed asi3.counters.counter_id property limits
    • Improved example values
    • Revised various descriptions

  • 1.0.0

    • First release version

Firmware compatibility table:

Device Firmware VersionOpenAPI Version
2.16.x.x1.0.0, 1.0.1
2.20.x.x1.1.0
APIOAS3.0
Pepperl-Fuchs

Pepperl-Fuchs_RFID_ReadWrite_Device

PUBLIC | PUBLISHED

Pepperl+Fuchs RFID Read/Write Device

This OpenAPI specification describes the RESTful API endpoints for the Pepperl+Fuchs RFID Read/Write Device.

Authenticate: How It Works

In order to authenticate the RESTful API to the devices, a client has to handle JSON Web Tokens.
JWTs are used for a short-lived authentication between the client and the device.

What is JSON Web Token (JWT)?

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way
for securely transmitting information between parties as a JSON object.
This information can be verified and trusted because it is digitally signed.

What is the JSON Web Token structure?

A JSON Web Token (JWT) consists of 3 parts separated by a period (.). The header and the payload are
JSON objects that are serialized to UTF-8 bytes and then encoded using base64url encoding.

  • Header

  • Payload

  • Signature

As a result, a JWT typically takes the following form:

{base64url encoded header}.{base64url encoded payload}.{base64url encoded signature}

Header

The header consists of two parts: the type of the token, e.g. JWT, and the signing algorithm used, e.g. HMAC SHA256 or RSA.

For example:

{"alg" : "HS256", "typ" : "JWT"}

Payload

The second part of the JWT is the payload that contains the claims.
Claims are statements concerning an entity (typically, the user) and additional data.

Some frequently used typical standard claims are the following:

  • Subject (sub): The name of the authenticated subscriber

  • Issued at (iat): The timestamp at which the token was created

  • Expiration time (exp): The timestamp at which the token expires

A typical example for a payload is the following:

{"sub": "John Doe", "iat": 1584529761, "exp": 1584529821}

Signature

The signature is used to verify that the message has not been changed along the way.

In order to create the signature, sign the following parts of JWT information:

  • The base64UrlEncode(header)

  • The base64UrlEncode(payload)

For example, when using the HMAC SHA256 algorithm, the signature will be created in the following way:

HMACSHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload), 256-bit-secret )

Putting All Signature Parts Together

The resulting signature consists of three base64-url strings, each being separated by a period.

The following example shows a JWT with a header and a payload that were previously encoded
and signed with an API key secret.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJKb2huIERvZSIsImlhdCI6MTU4NDUyOTc2MSwiZXhwIjoxNTg0NTI5ODIxfQ.KzWoTnuto_VPtkYiOROyfZ80zL_tIY6eC4smVPjmtEs

How the Authentication Works

  • A client sends the user name/password combination to the server.

  • The server validates the authentication.

  • If the authentication is successful, the server creates a JWT.

  • If the authentication fails, the server issues an error message.

  • After an initial successful authentication, each further client request supplies the JWT in the following way.

Authorization: Bearer <jwt_token>

  • Upon receiving the JWT, the server validates the JWT and issues a confirmation message. If the JWT cannot be successfully validated, the server issues an error message.

Examples for Using cURL

Use the Command-Line Tool (cURL) in order to Request the JWT

Request:

c url -H "Content-Type: application/json" --request POST 'http://192.168.0.2/api/auth/login' --data '{ "username":"admin", "password":"12341234" }'

Response:

{ "token": "<jwt_token>" }

Example for using with Python


import requests

import json


hostname = "http://<ipAddress>"

headersList = {
"Content-Type": "application/json"
}


# Login


rsp = requests.post(
  hostname + "/api/auth/login",
  json={
    "username": "admin",
    "password": "ADMINADMIN"
  },
  headers=headersList,
  timeout=10)

token = rsp.json()['token']

headersList["Authorization"] = f"Bearer {token}"


# Get the identification of the device


rsp = requests.get(hostname + "/api/identification", headers=headersList, timeout=10)

identification = rsp.json()

print(identification)

Changelog:

  • 3.0.1
    • Changed property name time to uptime of rfid.tag.data.antennas.antenna.data.items.item.base schema
    • Added property time to rfid.tag.data.antennas.antenna.data.items.item.base schema
    • Added property persistent_error_messages to common.system.reset.mode schema
  • 3.0.0
    • Changed resolution of property uptime from seconds to milliseconds of common.system.events schema
    • Changed property name time to uptime of common.system.events schema
    • Added optional time property to common.system.events schema
    • Added /system/time paths and schemas
    • Added POST /users/{user_id}/change-password path and schema
    • Added more detailed error enums to common.system.upload.error schema
    • Added read_only and link_state properties to common.network.interface schema
    • Added HTTP status code 202 (Accepted), 429 (Busy) and 500 (Internal Server Error) to PUT /system/fieldbus/configuration
    • Added HTTP status code 202 (Accepted), 429 (Busy) and 500 (Internal Server Error) to POST /system/reset and error object for HTTP status code 400 and 500
    • Changed power_transmit and transmission_channels schemas of rfid.antennas.antenna schema
    • Added DELETE /rfid/tag/data and DELETE /rfid/tag/data/{antenna_id} paths and schemas
    • Added TAG_PRESENT enum to rfid.outputs.event schema
    • Added HTTP status code 500 (Internal Server Error) to all /rfid path schemas
    • Added HTTP status code 501 (Not Implemented) schema
    • Revised various descriptions
  • 2.0.0
    • Changed default server schema to http
    • Changed global.id schema to type integer
    • Changed time property of common.system.events.event schema to global.uptime.seconds
    • Added contact and license information
    • Added production_date property to identification schema
    • Added global.uptime.seconds and global.uptime.milliseconds schemas
    • Added HTTP status code 429 (Busy) to all path schemas
    • Added HTTP status code 404 (Not Found) to POST /system/firmware/update path
    • Added /system/fieldbus paths and schemas
    • Added /system/network/interfaces paths and schemas
    • Added PUT /rfid/io/inputs path and schema
    • Added PUT /rfid/io/outputs path and schema
    • Added POST /rfid/tag/kill and POST /rfid/tag/{antenna_id}/kill paths and schemas
    • Added POST /rfid/tag/lock and POST /rfid/tag/{antenna_id}/lock paths and schemas
    • Revised GET and/or PUT schema for following paths:
      • /rfid/io
      • /rfid/io/inputs
      • /rfid/io/inputs/{input_id}
      • /rfid/io/outputs
      • /rfid/io/outputs/{output_id}
      • /rfid/tag/tasks
      • /rfid/tag/tasks/{antenna_id}
      • /rfid/tag/active-tasks
      • /rfid/tag/active-tasks/{antenna_id}
    • Revised various descriptions
  • 1.0.0
    • Refactored tag/transponder endpoints and component schemes
    • Minor refactoring of antenna component schemes
    • Minor refactoring of input component schemes
  • 1.0.0-beta.0
    • First beta version

Firmware compatibility table:

Device Firmware VersionPepperl+Fuchs RFID Read/Write Device OpenAPI Version
V2.1.23.0.1
V2.1.0, V2.1.13.0.0
V1.2.x2.0.0
V1.1.x1.0.0
APIOAS3.0
Pepperl-Fuchs

Sensorik4.0

PUBLIC | PUBLISHED

Pepperl+Fuchs Sensorik4.0®

This OpenAPI specification describes the endpoints for Pepperl+Fuchs Sensorik4.0® devices that support a RESTful API.

Changelog:

  • 2.0.0
    • Changed default server schema to http
    • Changed global.id schema to type integer
    • Changed time property of common.system.events.event schema to global.uptime.seconds
    • Added contact and license information
    • Added production_date property to identification schema
    • Added global.uptime.seconds and global.uptime.milliseconds schemas
    • Added HTTP status code 429 (Busy) to all path schemas
    • Added HTTP status code 404 (Not Found) to POST /system/firmware/update path
    • Revised various descriptions
  • 1.0.0
    • Initial version

Authenticate: How It Works

In order to authenticate the RESTful API to the devices, a client has to handle JSON Web Tokens. JWTs are used for a short-lived authentication between the client and the device.

What is JSON Web Token (JWT)?

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed.

What is the JSON Web Token structure?

A JSON Web Token (JWT) consists of 3 parts separated by a period (.). The header and the payload are JSON objects that are serialized to UTF-8 bytes and then encoded using base64url encoding.

  • Header
  • Payload
  • Signature

As a result, a JWT typically takes the following form:

{base64url encoded header}.{base64url encoded payload}.{base64url encoded signature}

Header

The header consists of two parts: the type of the token, e.g. JWT, and the signing algorithm used, e.g. HMAC SHA256 or RSA.
For example:

{"alg" : "HS256", "typ" : "JWT"}

Payload

The second part of the JWT is the payload that contains the claims. Claims are statements concerning an entity (typically, the user) and additional data.

Some frequently used typical standard claims are the following:

  • Subject (sub): The name of the authenticated subscriber
  • Issued at (iat): The timestamp at which the token was created
  • Expiration time (exp): The timestamp at which the token expires

A typical example for a payload is the following:

{"sub": "John Doe", "iat": 1584529761, "exp": 1584529821}

Signature

The signature is used to verify that the message has not been changed along the way.

In order to create the signature, sign the following parts of JWT information:

  • The base64UrlEncode(header)
  • The base64UrlEncode(payload)

For example, when using the HMAC SHA256 algorithm, the signature will be created in the following way:

HMACSHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload), 256-bit-secret )

Putting All Signature Parts Together

The resulting signature consists of three base64-url strings, each being separated by a period.

The following example shows a JWT with a header and a payload that were previously encoded and signed with an API key secret.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJKb2huIERvZSIsImlhdCI6MTU4NDUyOTc2MSwiZXhwIjoxNTg0NTI5ODIxfQ.KzWoTnuto_VPtkYiOROyfZ80zL_tIY6eC4smVPjmtEs

How the Authentication Works

  • A client sends the user name/password combination to the server.
  • The server validates the authentication.
  • If the authentication is successful, the server creates a JWT.
  • If the authentication fails, the server issues an error message.
  • After an initial successful authentication, each further client request supplies the JWT in the following way.

Authorization: Bearer <jwt_token>

  • Upon receiving the JWT, the server validates the JWT and issues a confirmation message. If the JWT cannot be successfully validated, the server issues an error message.

Examples for Using cURL

Use the Command-Line Tool (cURL) in order to Request the JWT

Request:
c url -H "Content-Type: application/json" --request POST 'http://192.168.0.2/api/auth/login' --data '{ "username":"admin", "password":"12341234" }'

Response:
{ "token": "<jwt_token>" }

APIOAS3.0
Showing 1-3 of 3