APIs

Swagger UI

Swagger UI allows anyone to visualize and interact with the API’s resources without having any of the implementation logic in place. It’s automatically generated from OpenAPI (formerly known as Swagger) Specification, with the visual documentation making it easy for back end implementation and client side consumption.

Swagger UI authorization uses an implicit authentication with an active azure account with a proper access to the Azure Active Directory of the platform. Usually a test user is no provided to our clients, but Swagger UI could still be used to play with the services endpoints and reference the relevant models, request and response formats.

To test an API method a few steps must be followed:

  1. Click on Authorize button.

Figure 1: Swagger API - Authorize button

  1. Select the given scope:

Figure 2: Swagger API authorization

  1. Sign in with an Azure account:

Figure 3: Sign in with Microsoft account

Figure 4: Swagger API - Available authorizations

Data API

Data API has GraphQL support to traverse the organizational structure and retrieve tags of interest. This API returns Raw data only!

Data API Swagger

To open Swagger Data API navigate to url : https://upkip-data-api.azurewebsites.net

Figure 5: Swagger - Data API

GraphQL

The GraphQL data query language is:

GraphQL Schema

A GraphQL schema is a description of the data clients can request from a Data API. It also defines the queries and mutation functions that the client can use to read and write data from the GraphQL server. In other words, you specify your client or application UI data requirements in your GraphQL schema.

GraphQL API refers to graph structures defined in the schema, where nodes define objects and edges define relationships between objects. The API traverses and returns application data based on the schema definitions, independent of how the data is stored. For more info about GraphQL go to http://graphql.org/learn/

Data API GraphQL

Executing the GraphiQL request (1) returns URL of GraphiQL -

https://upkip-data-api.azurewebsites.net/graphiql/

Figure 6: Data API: GraphiQL and GraphQL requests

Navigating to returned URL is opened GraphiQL. GraphiQL is an in-browser tool for writing, validating, and testing GraphQL queries/mutations.

Figure 7: GraphiQL tool

It is possible to execute queries by GraphiQL tool or by Swagger GraphQL request (2).

Data API GraphQL examples

Executing Data GraphQL API (2) request returns requested data.

Examples for GraphQL requests:

  1. Get all organizations with name, organization id and type id
    • Returns all organizations with organization id and type id

Example of query for Swagger request:

{
"query":"{  _all {    name    orgid    typeid  }}"
 }

Response:

{
	"data": {
		"\_all": [{
				"name": "TestLab",
				"orgid": 2,
				"typeid": 2
			}, {
				"name": "Demo Organization",
				"orgid": 5,
				"typeid": 2
			}
		]
	}
}
  1. Get a single organization by organization id with its name and the names of all organizational items related to the organization
    • Returns for organization names of all organization items

Example of query for Swagger request:

{ 
"query":"{ org(orgid: 5) { name items { name } }}"
}

Response:

{
	"data": {
		"org": {
			"name": "Demo Organization",
			"items": [{
					"name": "Factory"
				}, {
					"name": "Department"
				}, {
					"name": "matrikon"
				}
			]
		}
	}
}
  1. Get a single organization by organization id with its name organization id and type id with all related organizational items and all tags and properties for each organizational item.
    • Returns a full structure of organization items, machine tags and properties.

Example of query for Swagger request:

{
"query":"{ org(orgid: 5) { name orgid typeid items { orgitemid name typeid parentid tags { tagid tagname tagdescription valuetype serverid type { name typeid valuetype } } properties { type value } } }}"
}

Alerts API

Alerts API returns active or stopped warning by specified severity or Organization Item ID.

Alerts API Swagger

To open Swagger Alerts API navigate to url : https://upkip-alerts-api.azurewebsites.net

Figure 8: Swagger - Alerts API

Analysis API

Analysis API returns all KPI data for specified Machine or Work Order and KPIType.

There are requests for each KPI Type returning:

The KPITypes are different for Machines and Work Orders.

KPI Types for Machines:

KPI Types for Machines with aggregated functions:

The requests for both KPI Types are executed with aggregated functions when returning the list of values for period, specified with after, before or between datetimes.

The AggregateFunction types are:

KPI Types for Work Orders:

Using KPI Types for work orders are returned different parameters of work orders.

KPI Types for Work Orders Parts:

Using KPI Types for work orders parts are returned different parameters of work orders parts.

Analysis API Swagger

To open Swagger Analysis API navigate to url : https://upkip-analysis-api.azurewebsites.net

Figure 9: Swagger - Analysis API

SmartThings API

SmartThings API returns data for factory layout configurations or machines visualized on Factory Layout dashboard.

SmartThings API Swagger

To open Swagger SmartThings API navigate to url : https://upkip-smartthings-api.azurewebsites.net

Figure 10: Swagger - SmartThings API