1. Introduction

FORCE Bridge API is the application programming interface for the Internet of Things in a production environment, used in so called Industrial IoT Platform. As such, FORCE Bridge API is the interface between the objects of the production environment and the IT infrastructure of a production plant.

FORCE Bridge API is, so to speak, the bridge between the real production site and the IT systems and applications used for its effective and efficient organization.

The Industrial IoT platform fulfills two functions:

  1. FORCE Bridge API provides a complete digital image of a production plant with its relevant objects including their states. The objects consist of real world entities such as human resources, machines or tools as well as abstract entities such as production orders or operations.
  2. FORCE Bridge API ensures the organizational interoperability [1] of humans, production facilities and IT systems of a production plant in the sense of maximizing resource effectiveness and process efficiency.

The documentation for the API consists of different self-contained but mutually constructive parts. Each of these parts looks at a specific section of the API, first explains the technical background and ends with one or more example programs using the ADK.

1.1. Technical Base Knowledge

FORCE Bridge API connects your application to an IoT platform.

Your application can use the API to access data or send commands to the FORCE runtime or to listen for events which occur in the system.

  • Every API access is performed via HTTP(S).

    Request payloads are are formatted as application/json.

    Response payloads are formatted as application/json or application/hal+json.

  • OAuth2 is used for all authentication.

    All API requests must be authenticated or you will receive a 401 Unauthorized error response (see Authentication).

  • FORCE Bridge API is an explorable API and provides everything as a resources.

  • Every resource can be identified by its universal unique identifier (UUID).

Note

The complete Swagger specification of FORCE Bridge API is available here.

1.1.1. Explorable API

Response payloads are enriched with hyperlinks using the Hypermedia Application Language (HAL).

HAL is a simple format that provides a set of conventions for expressing hyperlinks in JSON - it’s basically just plain old JSON with hyperlinks! This encourage developers to build applications that use these hyperlinks to navigate between resources instead of using hard-coded URLs.

The following fields can be expected on every resource:

  • properties - The regular properties of the resource
  • _links - A JSON object containing a set of URL paths relative to the API base url
  • _embedded - A JSON object containing other resources embedded inside the current resource.

1.1.1.1. Collections

A set of resources is considered a collection.

1.1.2. Revisioning

The API is revised by identifiers in the URI.

Examples:

forcebridgepublish.force.eco:24443/ffwebservices/api/v1/operations

forcebridgepublish.force.eco:24443/ffwebservices/api/v2/operations

The version of the API is revised (increased) only when a breaking change in one of the webservices occurs. Breaking changes are:

  • Removal of a JSON property
  • Renaming of a JSON property
  • General restructuring in the design of existing representations
Breaking changes are not:
  • Adding JSON properties
  • Adding new webservices

Note

Please note that revisioning is global. This means that a webservice can return the same response for different versions (if no change has been made to this specific webservice)

It is possible that a new release adds new JSON properties to the response. This does not increase the webservice version. To ensure downward compatibility, every client communicating with the Bridge API should process new properties only if needed.

1.1.3. HTTP Requests

Where possible the API strives to use appropriate HTTP methods for each action.

Method Description
GET Used for retrieving resources.
POST Used for creating resources or executing an action, among other things.
PUT Used for replacing resources.
DELETE Used for deleting resources.

Headers

Key Value
authorization Base64 encoded client id and client secret
accept-header application/json or application/hal+json
accept-language en-GB (default), en-US, de-DE, zh-CN

1.1.4. HTTP Status Codes

The API attempts to return appropriate HTTP status codes for every request.

Code Description
200 OK Success.
201 Created The request succeeded and resulted in a new resource being created.
The Location header of the response contains the URI of the new resource.
202 Accepted The request has been accepted for processing, but processing has not been completed.
204 No Content The request succeeded but the server is not returning any content.
This is the response for most DELETE requests.
400 Bad Request The request was invalid or cannot be otherwise served.
An accompanying error message will explain further.
401 Unauthorized Authentication credentials were missing or incorrect.
403 Forbidden The request is understood, but it has been refused or access is not allowed.
An accompanying error message will explain why.
404 Not Found The URI requested is invalid or the resource requested, such as an event, does not exist.
415 Unsupported Media Type The request entity has a Content-Type that the server does not support.
500 Internal Server Error Something is broken.
504 Gateway Timeout The server, while acting as a gateway or proxy, did not receive a timely response
from the upstream server it needed to access in attempting to complete the request.

1.1.5. Authentication

FORCE Bridge API uses the OAuth 2.0 protocol for authentication.

Important

OAuth is only secure if it is used via the TLS/SSL protocol, so every request and API endpoints must use HTTPS.

Attention

Tokens are Passwords: Keep in mind that your application’s client id, client secret and access tokens should be considered as sensitive as passwords and should not be shared.

All applications follow a basic pattern when accessing the FORCE Bridge API. At a high level, you follow three steps:

  1. Obtain an access tokens
    In order to make an authentication request to the API, your application must first obtain an OAuth Access Token using the Client Credentials Flow.
  2. Use the access token to perform requests
    After your application obtains an access token, it sends the access_token property in a token response in a Bearer authorization header when making API requests.
  3. Refresh the access token when it expires
    Access token have limited lifetimes. If your application needs to request beyond the lifetime of an access token, it has to obtain a new access token.

1.2. How to Use FORCE Bridge API

In contrast to all other HTTP methods, POST must be used for different purposes in order to avoid countless calls in certain situations.

In a narrower sense, POST is used to create one or more new resources. To do this, the relevant collection is called with POST:

POST /{collection}

According to the hypermedial principle of RESTful architecture, whether a resource can be created is determined by the fact that the representation of the associated collection has a corresponding hyperlink. For example, Bridge API provides a hyperlink to the following method in the collection of tool assembly orders, via which applications can create new tools:

POST /tools/assemblyOrders

All properties of the tool assembly order are transferred with the method call to the IoT platform, which in turn responds with a representation of the newly created resource if the call was successful. In particular, the UUID of the newly created tool is announced in the response.

Another use of POST is to change the state of resources. To do this, the single resource in question is called with POST and a specification of the new state:

POST /{collection}/{id}/{state}

Bridge API allows a tool management system to set the state of a tool assembly order for example by the following call:

POST /tools/assemblyOrders/{toolAssemblyOrderId}/{toolAssemblyOrderStateId}

Although the PUT or PATCH method could also be used for this purpose, the calls would be much more cumbersome, since PUT requires that the properties that are not changed must also be passed.

On the other hand, it is difficult to reconcile it with the hypermedial concept of a REST architecture. The latter requires that an application in the representation of a resource is presented with all possible state transitions as hyperlinks and that each state transition is triggered by following a hyperlink. It is possible to provide the following reference in HAL:

"updateToolAssemblyOrderState": {
   "method": "POST",
   "embeddable": false,
   "href": ".../tools/assemblyOrders/E446BB6B0C084CB09D0BC0319A8A1F1C/AVAILABLE"
}

With a PUT or PATCH method, on the other hand, the specification of the new state would have to be specified in the request body.

If hundreds of resources are to be updated in a single transaction, the repeated call of the PUT method would mean unnecessary communication effort and corresponding delays, because only one concrete resource can be addressed at a time with PUT.

Furthermore, there is a risk that the data in the IoT platform will be in an inconsistent state until the call sequence is completed. To avoid this, a transaction-safe POST method is also offered for certain purposes as an alternative to the repeated call of the PUT method. In this case, the following notation is used to indicate that resources are being processed:

POST /operations/forecastResults/update

In all of these cases, the POST method is used to create an update, with the actual effect of repeating the call of

PUT /operations/{operationId}/forecastResult

corresponds to. There are two more examples in Bridge API:

POST /operations/planningResults/update

POST /staffMembers/planningResults/update

Finally, POST is also used instead of the GET method. This is because the GET method is not suitable for setting a large number of filter parameters when it is called. This problem occurs if the collections of production orders or operations are to be filtered explicitly by hundreds of order numbers. The POST method is therefore also provided for retrieving both collections. The following notation is used to indicate that such a POST method is intended for retrieving a collection and not for creating a new resource:

POST {collection}/search

1.2.1. How to Request OAuth Token

Applications have to use the Client Credentials Flow of the OAuth2 specification to get an access token that will provide access to FORCE Bridge API.

  1. Create a basic authorization header
    • URL encode you application’s client ID and client secret according to RFC 1738.
    • Concatenate the encoded client ID, a colon character (:) and the encoded consumer secret into a single string. Add “Basic” to the string.
    • Encode the string from the previous step in Base64

Example

Header:

{ Authorization : Basic xyz Content_Type: application/x-www-form-urlencode } Body: ‘grant_type=client_credentials&scope =read write’

Example code

{
        "// How to create Authorization String"
        "var encodedClientID = encodeURI(clientID); //encode with URLEncode"
        "var encodedClientSecret = encodeURI(clientSecret); //encode with URLEncode"
        "var pair = encodedClientID+':'+encodedClientSecret; //combine Strings with Semicolon"
        "var encodedPair = window.btoa(pair); //encode with Base64"
        "var authorizationValue = 'Basic' +encodedPair; //add Basic to the String"

}
  1. Obtain an access token
    • The encoded value must be exchanged for an access token.

1.2.2. How to Send POST Requests

The token URL is:
POST http(s)://$HOST:$PORT/ffwebservices/oauth/token

Headers

Name Value
authorization “Basic” + Base64 encoded clientid:clientsecret from prev. step
Content-Type application/x-www-urlencode

Parameters

Name Type Value
grant_type string Required. Value should be client_credentials
scope string Space-delimited string of the scopes you would like.

Scopes

Name Description
read Grants permission to call HTTP GET
write Grants permission to call HTTP POST, PUT, DELETE

Important

Token Expiration: You should write your applications to anticipate the possibility that a granted token may no longer work. Your application must authenticate again to get new access tokens. The time until a token expires is returned with the token response.

Java

Note

This task is performed automatically whenever a request is made, using the credentials provided during the initialization of the BridgeAPI object.

CURL

1
2
3
4
5
6
curl -X POST http(s)://$HOST:$PORT/ffwebservices/oauth/token \
     --header "accept:application/x-www-urlencode" \
     -d "client_id=$CLIENT_ID" \
     -d "client_secret=$CLIENT_SECRED" \
     -d "grant_type=client_credentials" \
     -d "scope=read%20write"

Example Request

{
        "//access_token must be requested first"
        "method": "POST",
        "headers": "{",
        "content-type": "application/json",
        "Authorization": "'Bearer ' +access_token"
}

Example Response

{
        "access_token": "537517ab-faa3-4ad2-8ae5-37ff91ffb7c0",
        "token_type":   "bearer",
        "expires_in":   42523,
        "scope":        "read write"
}

Footnotes

[1]Interoperability describes the skill to exchange and make use of information between two different systems.