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 proper access to the Azure Active Directory of the platform. Usually, a test user is not 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:
- Click on Authorize button.
Figure 1: Swagger API - Authorize button
- Select the given scope:
Figure 2: Swagger API authorization
- Sign in with an Azure account:
Figure 3: Sign in with Microsoft account
- After all steps are completed, the API methods will be available for testing:
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
- Swagger Data API is opened
Figure 5: Swagger - Data API
GraphQL
The GraphQL data query language is:
- A specification. The spec determines the validity of the schema on the API server. The schema determines the validity of client calls.
- Strongly typed. The schema defines an API's type system and all object relationships.
- Introspective. A client can query the schema for details about the schema.
- Hierarchical. The shape of a GraphQL call mirrors the shape of the JSON data it returns. Nested fields let you query for and receive only the data you specify in a single round trip.
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:
- 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
}
]
}
}
- 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"
}
]
}
}
}
- 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
- Swagger Alerts API is opened
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:
- Last value
- Values before specified DateTime
- Values after specified DateTime
- Values in the specified time range (between)
The KPITypes are different for Machines and Work Orders.
KPI Types for Machines:
- AlarmCount – returns the last alarms count for machine or alarms count for the period
- Downtime - returns the last machine Downtime status or Downtime statuses for period
- OEE - returns in percentage the last value of machine OEE or list of machine OEE for period
- OEE.Availability – returns in percentage the last value of machine Availability or list of machine availability values for the period
- OEE.Performance – returns in percentage the last value of machine Performance or list of machine performance values for the period
- OEE.Quality - returns in percentage the last value of machine Quality or list of machine quality values for period
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 the period, specified with after, before or between DateTime.
- DowntimeSummary – returns in seconds the aggregated values for Downtime statuses for the specified period.
- StatusSummary - returns in seconds the aggregated values for machine statuses for the specified period.
The AggregateFunction types are:
- min - returns the lowest value over a given timeInterval.
- max - returns the highest value over a given timeInterval.
- count - counts the number of points that contains a non NULL value over the given timeInterval.
- mean - returns the arithmetic mean (average) over a given timeInterval.
- mode - returns the most frequent value(s) over a given timeInterval.
- median - returns the middle value from a sorted set of values over a given timeInterval.
- sum - outputs the sum of all values over a given timeInterval.
- first - it will output the first point for each group by timeInterval.
- last - it will output the last point for each group by timeInterval.
KPI Types for Work Orders:
Using KPI Types for work orders are returned different parameters of work orders.
- OrderActualRemainingWork - returns in percentage work order actual remaining work
- OrderEstimatedRemainingWork - returns in percentage work order estimated remaining work
- OrderRemainingWorkDeviation – returns in percentage the remaining work deviation of work order
- OTD – returns in days the work order OTD
KPI Types for Work Orders Parts:
Using KPI Types for work orders parts are returned different parameters of work orders parts.
- OrderPartTimePerItem – returns in seconds part time per item
- PartActualRemainingWork – returns in percentage part actual remaining work
- PartCostDeviation – returns in hours part cost deviation
- PartEstimatedRemainingWork – returns in percentage work order part estimated remaining work
- PercentScrapPartsPerOrder - returns in percentage work order part actual remaining work
Analysis API Swagger
To open Swagger Analysis API navigate to URL : https://upkip-analysis-api.azurewebsites.net
- Swagger Analysis API is opened
Figure 9: Swagger - Analysis API
SmartThings API
SmartThings API returns data for factory layout configurations or machines visualized on the Factory Layout dashboard.
SmartThings API Swagger
To open Swagger SmartThings API navigate to URL : https://upkip-smartthings-api.azurewebsites.net
- Swagger SmartThings API is opened
Figure 10: Swagger - SmartThings API