Work with your REST 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 tool for making HTTP requests.

Considerations for Choosing a REST Client

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

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

With a 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.

How You Send HTTP Requests Using cURL

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://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/activities'

Get an activity

GET

 
curl -X 'GET' \
     -u '<CLIENT_ID>@<INSTANCE_NAME>:<CLIENT_SECRET>' \
     -H 'Accept: application/json' \
     'https://<instance_name>.fs.ocs.oraclecloud.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://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/activities/4225269'

How You Send HTTP Requests Using Clients

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 REST web services.

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

Operation Response/Payload Example

GET: Get an activity.

Request URL:

https://<instance_name>.fs.ocs.oraclecloud.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://<instance_name>.fs.ocs.oraclecloud.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",
...
}