API Introduction and Overview

Introduction

The following document outlines the public integrations currently available using the REST API with the PDS software.

A REST API is provided for data connectivity and synchronisation from iPads in the field and for system integration with external systems.

API Background

Tomcat Server (API Container)

The PDS API container service is built using a microservices architecture, allowing the server to infinitely scale to a high level of usage applied by both customer, via iPad, and customer developed automated solutions for integrating with the PDS software. By using microservices, the PDS API services are able to easily increase hardware resources as demand increases overtime.

The PDS API services are deployed into PDS’s secure infrastructure, and each component of the PDS infrastructure communicates internally within a firewalled environment. All communications external to the datacenter are encrypted using industry level 128 bit SSL.

The PDS API Services are built using Java™, The Spring Framework™ and other open source technologies.

Security

Inter-Service Communication

All inter-service communication is carried over Secure Socket Layer(SSL)/Transport Security Layer (TSL) to protect data in transit between each of the services. The purpose is to create a secure tunnel protected by 128-bit or higher Advanced Encryption Standard (AES) encryption.

External Communication

All external communication, that is communication that is taking place over the public internet, is carried over Secure Socket Layer(SSL)/Transport Security Layer (TSL) to protect data in transit between the service and the clients web browser or mobile device. The purpose is to create a secure tunnel protected by 128-bit or higher Advanced Encryption Standard (AES) encryption.

Authentication

The PDS software utilises the Spring Security Framework for authentication and authorization of users.

“Spring Security provides comprehensive security services for Java EE-based enterprise software applications. There is a particular emphasis on supporting projects built using The Spring Framework, which is the leading Java EE solution for enterprise software development. If you’re not using Spring for developing enterprise applications, we warmly encourage you to take a closer look at it. Some familiarity with Spring - and in particular dependency injection principles - will help you get up to speed with Spring Security more easily.”

By using the Spring Security framework, the PDS software can provide state of the art authentication and authorization management, while maintaining the flexibility to integrate into alternative authentication providers such as LDAP or OAuth.

User accounts for the PDS software are stored and managed in the PDS (User Management) Console/Database. Each user account is required to have a password, which is hashed when stored. This hash is salted with some additional identifiable information for extra security.

The Spring Security framework provides customisable and flexible password polices, allowing for password complexities, account lock out and more.

Integrations

The PDS software allows for 3^rd party systems to INSERT/UPDATE or RETRIEVE data via a highly secure, scalable and customisable API.   The PDS API utilises enterprise design patterns to allow for a send and forget style of integration, with the mandate that the data being inserted/updated will make it into the database.

HTTP Requests and Responses

HTTP Post and PUT

Creating resources

The HTTP PUT and POST methods are used for sending information to the API.

• A POST method will create new data in PDS.
• The only parameter required is api_key.
• The content-type header should be set as “application/json”.
• The encoding-type header should be set as “UTF-8”.
• Only JSON formatted requests are accepted, XML requests are not currently supported.

You should check the response from each API call and not assume that it will be completed successfully.

Creating many resources

It is possible to submit more than one piece of data in a single API call. All elements in the request must be of the same type. You cannot however insert say both an Idler Failure record and Tonnes data within the same request.

HTTP Get

Retrieving resources

The HTTP GET method is used for retrieving information from the API.

• A GET method will retrieve data from PDS.
• No headers are currently needed.
• The api_key parameter is required.
• Other parameters may or may not be required.
• The returned data will be displayed in JSON format.

Parameters

Most GET requests have mandatory and/or optional parameters as listed in this document below. To use a parameter, the format is to use a ? at the end of the url, followed by the parameter name, then =, followed by the parameter value. To use multiple parameters, use an & to separate them. For example: https://api.pdsglobal.com/api/idler/idlerfailures/V1?api_key=ExampleAPIKey&businessName=Example Business Name

HTTP Response Codes and Errors

Codes Summary

Errors

Errors can occur within the API at 2 levels. Level 1 is during the acceptance of the data. The errors that occur here will be provided via the codes described in section 4.2.1.

The second type of errors occur when the processing queue attempts to insert the record into the database. The most common cause of errors at this point is data duplication. The API has a built in mechanism to detect duplicates in most of the defined entities.

If an error occurs during the processing and storing of the data, an error response will be added to a custom Error Endpoint, which can be retrieved by the calling system at anything during the process.

Our recommendation would be to call the error endpoint at intervals 1/5 that of the ‘Create’ endpoint.

API Security

Users who wish to access the PDS software via the API must use an API Key. Each user is issued with a unique key which is generated by the system and can be viewed in User Management. Only users with the ‘API User’ role assigned have access to the API. If you do not have an API Key please contact your PDS system administrator or support@pdsglobal.com for assistance.