Work with your REST API Client

It's easy to use and test REST APIs because they use HTTP methods to send and receive content with just about any programming language or tool. So, let's first choose a REST API client for making HTTP requests.

Choosing a REST API Client

You can choose among many API clients that interact with Oracle Field Service Cloud, such as:

  • A standalone client, such as Postman or Advanced REST Client
  • Your connecting application's client
  • The cURL command-line utility

With a REST API client you can:

  • Test the username, password, and request URL for your REST API account.
  • Use the collected information to construct and send various types of HTTP requests, such as those to create, update, or delete records.

Using cURL to Send HTTP Requests

cURL is a command-line tool that uses a URL format to transfer data. You can use it to test the format that you use for your REST API requests. It's available in most UNIX, Windows, and Macintosh environments. See Use cURL for installation instructions.

You can use the following cURL options with REST services.

cURL Option Description

-u

Specifies the application credentials and instance name to use when authenticating with the server. It uses the following format:-u <CLIENT_ID>@<INSTANCE_NAME>:<CLIENT_SECRET>

-d

Sends data as a JSON (JavaScript Object Notation) request body to the server. If you begin the data with the @ sign, then the content that occurs after the @ sign must contain the name of the file that the REST API uses to get the data.

-F

Identifies form data in JSON format on your local computer.

-H

Includes an extra HTTP header in the request. You can specify multiple headers. Precede each header with the -H option. For example:

  • Content-Type: Format of Request Body (for example, with a POST command)
  • Accept: Format of Response Body
  • X-Auth-Token: Authentication Token

-o

Writes the output to file instead of to stdout. Use the following format to specify the file name:

-o <file>

-X

Specifies the request method to use when communicating with the HTTP server. If you do not include -X, then the REST API uses GET, by default.

The following examples use cURL.

Operation Type cURL Command

Create an activity

POST

curl -X 'POST' \ -u '<CLIENT_ID>@<INSTANCE_NAME>:<CLIENT_SECRET>' \
     -H 'Content-Type: application/json' \
     --data-binary '
{
    "resourceId": "33011",
    "date": "2016-03-18",
    "activityType": "Trouble-call",
    "apptNumber": "testApptNumber_NMAZFFKBMB",
    "customerName": "testCustomerName_NMAZFFKBMB",
    "language": "en",
    "timeZone": "Eastern",
    "duration": 40
}' \
     'https://api.etadirect.com/rest/ofscCore/v1/activities'

Get an activity

GET

curl -X 'GET' \
     -u '<CLIENT_ID>@<INSTANCE_NAME>:<CLIENT_SECRET>' \
     -H 'Accept: application/json' \
     'https://api.etadirect.com/rest/ofscCore/v1/activities/4225269'

Update an activity

PATCH

curl -X 'PATCH' \
     -u '<CLIENT_ID>@<INSTANCE_NAME>:<CLIENT_SECRET>' \
     -H 'Content-Type: application/json' \
     --data-binary '{
    "apptNumber": "ChangedApptNumber",
    "customerName": "ChangedName"
}' \
     'https://api.etadirect.com/rest/ofscCore/v1/activities/4225269'

Using REST API Clients to Send HTTP Requests

You can use standalone clients, third-party browser extensions, or add-ons, such as the Advanced REST Client, to manage requests to Oracle Field Service Cloud Service REST web services.

The following table includes examples of the GET and POST operations using a REST API client.

Operation Response/Payload Example

GET: Get an activity.

Request URL:

https://api.etadirect.com/rest/ofscCore/v1/activities/4225449

{
   "activityId": 4225449,
   "resourceId": "RXXXXX123",
   "accessSchedule": "{\"schedule\":[{\"daysOfWeek\":[\"Mon\",\"Tue\",\"Wed\",\"Thu\",\"Fri\",\"Sat\",\"Sun\"],\"hours\":[[\"07:00\",\"12:00\"]]}],\"exceptDates\":[\"2017-08-18\"]}",
   "resourceInternalId": 8101380,
   "date": "2017-08-17",
   "apptNumber": "ApptNumber",
   "recordType": "regular",
   "status": "pending",
   "activityType": "4",
   "duration": 39,
   "travelTime": 30,
   "timeSlot": "all-day",
   "customerName": "John Doe",
   "streetAddress": "12345 Stuyvesant Ave",
   "city": "Brooklyn",
   "postalCode": "11221",
   "stateProvince": "NY",
   "language": "en",
   "languageISO": "en-US",
   "timeZone": "(UTC-03:00) Buenos Aires - Argentine Time (ART)",
   "timeZoneIANA": "America/Argentina/Buenos_Aires",
...
}

POST: Create an activity.

Request URL:

https://api.etadirect.com/rest/ofscCore/v1/activities

Request:
{
      "resourceId": "RXXXXX123",
      "date": "2017-08-17",
      "apptNumber": "ApptNumber",
      "activityType": "4",
      "duration": 60,
      "timeSlot": "all-day",
      "customerName": "John Doe",
      "streetAddress": "12345 Stuyvesant Ave",
      "city": "Brooklyn",
      "postalCode": "11221",
      "stateProvince": "NY",
      "accessSchedule": "{\"schedule\":[{\"daysOfWeek\":[\"Mon\",\"Tue\",\"Wed\",\"Thu\",\"Fri\",\"Sat\",\"Sun\"],\"hours\":[[\"07:00\",\"12:00\"]]}],\"exceptDates\":[\"2017-08-18\"]}",
      "setPositionInRoute": {
          "position": "first"
      }
Response:
{
   "activityId": 4225449,
   "resourceId": "RXXXXX123",
   "accessSchedule": "{\"schedule\":[{\"daysOfWeek\":[\"Mon\",\"Tue\",\"Wed\",\"Thu\",\"Fri\",\"Sat\",\"Sun\"],\"hours\":[[\"07:00\",\"12:00\"]]}],\"exceptDates\":[\"2017-08-18\"]}",
   "resourceInternalId": 8101380,
   "date": "2017-08-17",
   "apptNumber": "ApptNumber",
   "recordType": "regular",
   "status": "pending",
   "activityType": "4",
   "duration": 39,
   "travelTime": 30,
   "timeSlot": "all-day",
   "customerName": "John Doe",
   "streetAddress": "12345 Stuyvesant Ave",
   "city": "Brooklyn",
   "postalCode": "11221",
   "stateProvince": "NY",
   "language": "en",
   "languageISO": "en-US",
   "timeZone": "(UTC-03:00) Buenos Aires - Argentine Time (ART)",
   "timeZoneIANA": "America/Argentina/Buenos_Aires",
...
}