APIs (Web Services) - Overview

Cornerstone provides our customers and partners the ability to easily integrate with Cornerstone using APIs (web services). APIs provide instant and programmatic access to Cornerstone data to support domain and reporting use cases. This includes on-demand access to do the following:

  • Read data from Cornerstone.
  • Create and update data in Cornerstone.

Important: Cornerstone's legacy API authentication framework for APIs, Session Token Service (STS), was deprecated in February 2020 and is fully retired and unavailable as of February 2021.

Implementation

The customer is responsible for any infrastructure and development to call or execute Cornerstone APIs. Cornerstone does not offer to develop custom code or custom APIs, and Cornerstone does not develop or debug customer's source code.

Terminology

The following terms are commonly used when discussing APIs:

  • REST (Representational State Transfer) - An architectural style for providing standards between systems on the web, making it easier for systems to communicate with each other.
  • OData (Open Data Protocol) - An open protocol (OASIS standard) that defines best practices for building and consuming RESTful APIs.
  • SOAP (Simple Object Access Protocol) - An XML-based protocol for exchanging structured information across domains.
  • JSON (JavaScript Object Notation) - A lightweight and text-based data-interchange format. JSON has become one of the fundamental industry standards to exchange data via web services because it is easy for humans to read and write and also easy for machines/browsers to parse and generate.
  • OAuth 2.0 (Open Authorization) - An industry standard authorization framework that supports the consumption of RESTful APIs.

API Explorer

API Explorer contains the most up-to-date documentation for all REST APIs. API Explorer enables developers and partners to easily browse all available REST APIs. Developers can learn about supported features, methods, and metadata. Developers can also download guidelines and access links to sample code.

To access the API Explorer, go to Admin > Tools > Edge > API Explorer. API Explorer can also be accessed directly at the following URL: http://apiexplorer.csod.com

Release Strategy

All clients reside on the same and latest web services version. New web services will be developed and deployed as part of the roadmap. Cornerstone does not support building custom APIs for each customer use case.

All new APIs will be developed as RESTful APIs. Any legacy SOAP web services that are still available are maintained, but they will not be further developed.

Trial Period

An unlimited trial period is available to try the Cornerstone APIs, Reporting APIs, or Bulk APIs. The trial period is available for non-productive environments (i.e., pilot, stage, and demo environments). To try an API, simply instal the integration in your Pilot, Stage, or Demo environment. The integration must be configured in each environment separately.

Pagination

To increase performance and to minimize the response size, Cornerstone web services utilize paging in its response. This means the caller will only retrieve a page of results, and not all the entities. Please review the API Explorer for the default and the maximum paging values per web service request.

  • Cornerstone API - The Cornerstone API must be sequentially called by incrementing the page number attribute in the URL query until Cornerstone stops returning results.
  • Reporting API - The Reporting API implements OData server-driven paging protocol. The service will inject a link into the page response to retrieve the next page of results.
  • Employee/OU API - Customers can control the number of records per page through the pageSize query parameter. The service will inject into the page response an encoded string named nextPageToken that is used to retrieve the next page of results. The nextPageToken has a time to live (TTL) of five minutes.

Registering an Application

Every application that you intend to integrate using Cornerstone's APIs and OAuth 2.0 must be registered within the Cornerstone Edge API Management page. This can be done by going to Admin > Tools > Edge > API management > Manage OAuth 2.0 applications > Register New Application

You can register multiple applications with Cornerstone to get a distinct client ID and secret for each application. A client ID and client secret are required to consume RESTful APIs. Note: The client secret is only displayed once, so be sure to copy it after registering an application. If you misplace the client secret, you must regenerate it in the Cornerstone portal.

Access can be provided to multiple APIs (e.g., Cornerstone APIs and Reporting APIs) at the same time. This can be specified when registering the application.

When registering an application, the OAuth 2.0 access token validity period can be configured.

Sample Code

The Cornerstone GitHub repository contains sample code for several APIs and in popular development languages.

https://github.com/cornerstoneedge

OAuth 2.0 Scopes, Security Permissions, and Constraints

Using Scopes, organizations can control the API endpoints to which an application has access and the HTTP operations (GET, POST, PUT, PATCH) which can be performed against those endpoints. For example, an organization may grant their application access to only read employee data.

Scopes are available for all RESTful APIs. The API Explorer contains which scope is required to execute a specific endpoint or HTTP operation. See Edge - API Explorer.

Certain APIs allow organizations to further restrict an application's access using security permissions and constraints. For example, with the Express Class API, organizations can choose to allow their application to create express class records users from a specific division or geographical region. To determine whether an API requires permissions and supports constraints, review the list of permissions required for each API and the descriptions of each permission. See API (Web Services) Technical Specifications.

The following HTTP operations may be available for an API:

  • GET - Read data
  • POST - Create new data
  • PATCH/PUT - Update existing data
    • In Cornerstone, some web services supporting PATCH, others are supporting PUT to update data. With PUT request, you must send the full payload as the request whereas with PATCH, you only send the parameters which you want to update.

The OAuth 2.0 framework describes several grant flows or methods for acquiring an API access token. Cornerstone only supports the Client Credentials grant flow.

Frequently Asked Questions (FAQs)

Content

The following information is available within this folder. Click a link to navigate directly to the appropriate topic: