Introduction to EMS Platform Services

This topic contains introductory information regarding EMS Platform Services:

See Also: Architecture and Prerequisites and Requirements

Overview

What is EMS Platform Services?

EMS Platform Services is a Platform as a Service (PaaS) solution offering modern, RESTful APIs. Platform Services enables the development of multi-platform applications that can be customized, cloud-based, scalable, and easily integrated. It is a true middle tier, providing a business and resource layer that enables the central development of applications, reducing complexity and development time. Platform Services fosters innovation by ensuring easy maintenance and efficient management of an application's life cycle.

In the current EMS architecture, databases exchange business logic directly with applications in the business tier. The Platform Services architecture creates an intermediary layer of business logic and resources that provides a buffer between the applications and EMS databases. Fixes, enhancements, and/or new features can now be dispersed simultaneously to all products through Platform Services.

See Also: EMS Platform Services Architecture

Get Started with Integrations

Platform Services provides RESTful APIs that empower customers and partners to build custom, multi-platform applications connected to EMS. Any client/device accessing EMS Platform Services must be a registered Integration Client. The one exception is that anyone can access the public (open) API requests (/status, /health, /clientauthentication).

There are two types of Integrations:

  • Custom – Customer applications

  • Partner – Third-party EMS partner applications (e.g., 7PointsSolutions, Pepperdash, control concepts, etc.)

Partner and Custom types can be classified as either of the following two client sub-categories:

  1. User-based – User-based clients (EMS Mobile, EMS for Outlook) need to authenticate as a user to perform any actions. These clients need an integration client role with minimal access to the following API resources (above and beyond public resources):

    • /authentication

    • /logging

  2. Non-user Based – Non-user Based clients (EMS Kiosk, EMS Room Sign App) provide functionality independent of users but also support user-like functionality (such as Check-In and on-the-fly room reservations). These clients need a role with wider access.

Begin the Integration Process

To start the integration process:

  1. Verify if you have a license for adding Integrations. EMS Licensing manages a numeric count of both Custom and Partner Integration Types. Contact your EMS Sales Representative for a license for EMS Platform Services. View Licensing Requirements (see Licensing Requirements for Platform Services). 

  2. Access Platform Services documentation (e.g., https://Yourcompany.com/EmsPlatform/swagger). 

  3. Access admin portal for Platform Services (e.g., https://Yourcompany.com/EmsPlatform/admin) to create a new Integration Client. See Configuring Platform Services in the Admin Portal for more information. 

    Creating a new Integration Client will generate a Client ID and Secret pair.

  4. Platform Services requires a valid JWT Authentication token to call any of the API resources with the exception of /public, /status and /clientauthentication. Before making any API request, you must first call /clientauthentication with a Client ID and Secret pair generated in the previous step.

    • The Client token returned from calling /clientauthentication should be applied to the x-ems-api-token header for subsequent API requests.

      There can be multiple active instances of a particular client interacting with the Platform. All devices that share a client/secret will share a common authentication token. If the token expires, all devices will need to authenticate again to get a new shared token.

  5. For API resources that require an authenticated web user, your integration client will need to request a web user authentication token for that user. To acquire an authentication token, call the /authentication requests.

  6. The Web token returned from calling /authentication should also be applied to the x-ems-api-token header; thus, replacing the client token with a user token.

    Refer to the API documentation to determine the appropriate token (i.e., client token or web token) for the header field.

API Documentation

Navigate to Platform Services URL (e.g. https://Yourcompany.com/EmsPlatform/swagger) to view the API documentation. You can also manually type in the URL (https://Yourcompany.com/EmsPlatform/swagger).

Base URL for All API Requests

All requests should be made to URL for EMS Platform Services (e.g., https://Yourcompany.com/EmsPlatform).

Date/Time Standards

All dates and times passed to the API requests follow RFC 3339 Standard and must be in UTC. 

All DateTimes follow the standard (e.g., 2008-09-08T22:47:31-07:00)

Common Response Codes

Response Code

Title

Meaning

200 Success Successful data call/pull
400 Bad Request Server could not understand the request due to invalid syntax
401 Invalid/Missing Client Credential User credentials are incorrect; invalid login info
500 Server Error General status code that indicates the server encountered an unexpected condition and could not fulfill the request
503 Service Unavailable Application pools are not currently enabled
519 Server Internal Error System requirements are not met

HTTP Request Methods

Method

Description

GET Requests data from a specified source.
POST Sends data to the API server to create or update a resource; data sent to the server is stored in the request body of the HTTP request.
PUT Sends data to the API server to create or update a resource (similar to POST). However, PUT requests are idempotent and calling the same PUT request multiple times will always produce the same result. Calling a POST request repeatedly might have the side effect of creating the same resource multiple times.
DELETE Deletes the specified resource.
PATCH Applies partial modifications to a resource.