fairsail rest api: guide for developers 2019-03-11آ this rest api guide for developers provides...
Post on 02-Aug-2020
Embed Size (px)
Fairsail REST API: Guide for Developers Version 1.02
Fairsail REST API: Guide for Developers © Fairsail 2015 2
© Fairsail 2015. All rights reserved.
This document contains information proprietary to Fairsail and may not be reproduced, disclosed, or used in whole or in part without the written permission of Fairsail.
Software, including but not limited to the code, user interface, structure, sequence, and organization, and documentation are protected by national copyright laws and international treaty provisions. This document is subject to U.S. and other national export regulations.
Fairsail takes care to ensure that the information in this document is accurate, but Fairsail does not guarantee the accuracy of the information or that use of the information will ensure correct and faultless operation of the service to which it relates. Fairsail, its agents and employees, shall not be held liable to or through any user for any loss or damage whatsoever resulting from reliance on the information contained in this document.
Nothing in this document alters the legal obligations, responsibilities or relationship between you and Fairsail as set out in the contract existing between us.
This document may contain screenshots captured from a standard Fairsail system populated with fictional characters and using licensed personal images. Any resemblance to real people is coincidental and unintended.
All trademarks and service marks mentioned in this document belong to their corresponding owners.
Fairsail REST API: Guide for Developers © Fairsail 2015 3
About this Guide 4 Related Guides 4
Fairsail REST API: Guide for Implementers 4
Using Fairsail Resources 6
Using cURL in the REST Examples 7
Authentication 8 Understanding Authentication 9 Defining Remote Access Applications 10 OAuth Endpoints 11 The Web Server OAuth Authentication Flow 12 The User-Agent OAuth Authentication Flow 16 The Username-Password OAuth Authentication Flow 19 The OAuth Refresh Token Process 21
Working with Fairsail HCM Resources 23 Working with Fairsail Team Member Resources 24 Working with Training Resources 25
Status Codes and Error Responses 27
Fairsail REST API: Guide for Developers © Fairsail 2015 4
About this Guide This REST API Guide for Developers provides an introduction to the key characteristics and architecture of the Fairsail REST API, using Fairsail resources, and authentication.
To use this document, you need a basic familiarity with software development, Web services, and the Salesforce user interface.
Fairsail REST API: Guide for Implementers
A step by step guide to setting up a web service between a customer server and the Fairsail database to enable REST API level access to Fairsail hosted data.
Typical target audience
You have responsibility for configuring the Fairsail system to support REST API access from a customer server.
Fairsail REST API: Guide for Developers © Fairsail 2015 5
Introduction Fairsail provides a REST API for external programs and systems to interact with the Fairsail technologies. This document describes how to use the Fairsail REST API.
Fairsail is built on the Salesforce Force.com platform. The Force.com platform has its own REST API which can be used to interact with any of the Fairsail data objects. However, such access is at the database layer of the Fairsail system, bypassing the business logic and part of the security layers of Fairsail. As such, use of the Fairsail REST API is recommended.
Use this Guide to understand:
• The Force.com REST API, on which the Fairsail REST API is based. The authentication and data formatting options are identical, and come from the same code base.
• The key characteristics and architecture of REST API. This will help you understand how your applications can best use the Fairsail REST resources.
• How to set up your development environment so you can begin working with REST API immediately.
• How to use REST API by following a quick start that leads you step by step through a typical use case.
Fairsail REST API: Guide for Developers © Fairsail 2015 6
Using Fairsail Resources A REST resource is an abstraction of a piece of information, such as a single data record, a collection of records, or even dynamic real-time information. Each resource in the Force.com REST API is identified by a named URI, and is accessed using standard HTTP methods (HEAD, GET, POST, PATCH, DELETE). The Force.com REST API is based on the usage of resources, their URIs, and the links between them. You use a resource to interact with your Fairsail or Force.com organization. For example, you can:
• Retrieve summary information about the API versions available to you.
• Obtain detailed information about a Fairsail object such as a Team Member or a Training record.
• Update or delete records.
To retrieve information about a Team Member, submit a request for the Versions resource. This example uses cURL on the na1 server instance:
Fairsail runs on multiple server instances, as does the underlying Force.com platform. The examples in this guide use the na1 instance. Your organization might use a different instance.
Important characteristics of the Fairsail (and Force.com) REST API resources and architecture:
Stateless Each request from client to server must contain all the information necessary to understand the request, and not use any stored context on the server. However, the representations of the resources are interconnected using URLs, which allow the client to progress between states.
Caching behavior Responses are labeled as cacheable or non-cacheable
Uniform interface All resources are accessed with a generic interface over HTTP.
Named resources All resources are named using a base URI that follows your Fairsail/Force.com URI.
Layered components The Fairsail REST API architecture allows for such intermediaries as proxy servers and gateways between the client and the resources.
Authentication The Fairsail REST API supports OAuth 2.0 (an open protocol to allow secure API authorization).
Refer to Authentication (see page 8) for more details.
Support for JSON and XML • JSON is the default. You can use the HTTP ACCEPT header to select either JSON or XML, or append .json or .xml to the URI (for example, /teammember/001D000000INjVe.json).
• Date-time information is in ISO8601 format.
• XML serialization is similar to SOAP API.
• XML requests are supported in UTF-8 and UTF-16, and XML responses are provided in UTF-8.
Case Sensitivity The urls and data field names are case sensitive. Use the case as defined within this document. /TeamMember/ is not the same as /teammember/
Fairsail REST API: Guide for Developers © Fairsail 2015 7
Using cURL in the REST Examples The examples in this guide use the cURL command line tool to send HTTP requests to access, create, and manipulate REST resources on the Fairsail/Force.com platform. cURL is pre-installed on many Linux and Mac systems. Windows users can download a version at curl.haxx.se/. When using HTTPS on Windows, ensure that your system meets the cURL requirements for SSL.
cURL is an open source tool and is not supported by Fairsail.
Fairsail REST API: Guide for Developers © Fairsail 2015 8
Authentication The Fairsail REST API uses the same authentication options as the Force.com REST API. This document describes the main options in outline. There are several good coding examples of using these available on the web, and any that work with the Force.com REST API will also work with the Fairsail REST API.
Please read the sections on authentication at the following site:
Authentication Understanding Authentication
Fairsail REST API: Guide for Developers © Fairsail 2015 9
Understanding Authentication Fairsail uses authentication to allow users to securely access data without having to reveal username and password credentials.
Before making REST API calls, you must authenticate the user using OAuth 2.0. To do so, you’ll need to:
• Set up a remote access application definition in Fairsail.
• Determine the correct OAuth endpoint to use.
• Authenticate the user via one of several different OAuth 2.0 authentication flows. An OAuth authentication flow defines a series of steps used to coordinate the authentication process between your application and Fairsail. Supported OAuth flows include:
o Web server flow, where the server can securely protect the consumer secret.
o User-agent flow, used by applications that cannot securely store the consumer secret.
o Username-password flow, where the application has direct access to user credentials.