Quick Start

Step 1: Consider Before You Start

Review the basics. If you're new to REST APIs, make sure you understand the basics of REST and JSON, and scan our list of important terms.

Review Roles and Privileges. You must have the necessary security roles and privileges to use the GET, POST, PATCH, and DELETE methods on your parent and child resources.

Review opt-in requirements. Some resources or their attributes may be associated with features that require opt-in before you can use them. You must make sure that you enable opt-in features before you start.

Choose a client. REST APIs connect software programs over the HTTP protocol. You need a software client to send the HTTP requests. In our examples, we use cURL. But, cURL isn't the only tool you can use. To help you choose one, see Work with your REST Client.

Step 2: Get Your Registered Application Credentials

To make a REST HTTP request, you need to gather a few bits of information:

REST Server URL. The URL for Oracle Field Service is https://<instance_name>.fs.ocs.oraclecloud.com.
Instance Name. The instance name is available on the Configuration > About screen of the Oracle Field Service application. Alternatively, you can use the alternate instance name displayed in service console.
Client ID and Client Secret. The credentials of the registered application that has permissions to access the required services.

Note:
To register the application in Oracle Field Service, you have to be an administrator. The administrator credentials can be found in the welcome email. For more information on how to register, see Authenticate and Authorize.

Step 3: Configure Your Client

With the information gathered so far, you're ready to configure your client to send a REST HTTP request.

Construct the request URL. The URL consists of the server name and the resource path:
```
https://<server>/<resource-path>
```
The <server> is the REST Server URL from Step 2, as in:
```
https://<instance_name>.fs.ocs.oraclecloud.com
```
The <resource-path> is the relative path or endpoint to the resource you're working with. You can pick any endpoint in All REST Endpoints. For example, we're interested in the 'activities' resource:
```
/rest/ofscCore/v1/activities/<activityId>
```
combine the REST Server URL and, in this example, the 'activities' resource path to get the complete request URL.
```
https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/activities/<activityId>
```
Determine the HTTP verb. The HTTP verb depends on the type of CRUD operation you are going to perform. In this case, the HTTP verb will be GET as we are going to retrieve records.
Provide your account information. Include your Client ID, Instance Name, and Client Secret (from Step 2) in the client. For example, if you are using cURL, you can specify your account information using the -u cURL command as follows:
```
-u <CLIENT_ID>@<INSTANCE-NAME>:<CLIENT-SECRET>
```
In a client such as Postman, you enter the ClientID, Instance Name, and Client Secret in the user name and password fields on the Authorization tab. This screenshot shows how to specify this information in Postman:
Set the media type, if required. Media type defines the structure of the HTTP payloads exchanged between the server and the client. If you're using cURL, you can specify a media type using the header -H option. In this case, it is not required as it is a GET request.

Note:
URL Encoding: It is essential to encode all URL parameters to ensure data integrity and prevent errors. Special characters and spaces should be percent-encoded. For example, spaces can be encoded as %20 or alternatively as +, and an ampersand (&) as %26. Adhering to RFC 3986 encoding standards is crucial for preventing malformed URLs and ensuring reliable API interactions.

For more on media types, see Supported Media Types.

When you're done, the cURL command should look like this:

curl -X GET "https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/activities/<activityId>"

If you're not familiar with any of the syntax used in the example, check out Work with your REST Client.

Step 4: Authenticate and Authorize

Now that you've configured the client with a complete request URL, it's time to authenticate and authorize. Authentication proves that the credentials are genuine, and authorization enforces the API access privileges for these credentials.

Authentication

Oracle Field Service REST APIs support the following mechanisms that the client uses to send authentication credentials:

HTTP Basic Authentication: Ensures secure and encrypted access to data over a network.
OAuth 2.0 Authentication: Streamlines integrations with Oracle products and other middleware.

You need to select one of the mechanisms. Let's look at our example using HTTP Basic authentication over SSL. Typically, the application credentials and instance name (from Step 2) are encoded in Base64 format and specified in the Authorization header using -H cURL option in the cURL command:

curl -X GET "https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/activities/<activityId>" -H "Authorization: Basic NTM0ZjgyYThkMWFjMmE0N2RhOWNmZTk1YTRjOGJmOWI4N2I2NjU1M0BvZnNjLTFkZTY3MC50ZXN0OmMwY2U5MzE3NjJmYjQxNGE2OWMwNjNhNGU5MmZhNjRkZmEwMjJkZjY5ZDNkOTE3Y2NkMGE0YWM4OTAwZGE5ZTI="

Alternatively, you can use the -u cURL option to pass the application credentials and instance name as in this example:

curl -X GET "https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/activities/<activityId>" -u "<CLIENT_ID>@<INSTANCE_NAME>:<CLIENT_SECRET>"

OR use the alternate instance name displayed in service console as in this example:

curl -X GET "https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/activities/<activityId>" -u "<CLIENT_ID>@<Alternate_INSTANCE_NAME>:<CLIENT_SECRET>"

For more information on different types of authentication, see Authenticate and Authorize.

Your authorization and authentication information gets passed in the Authorization key of the request header. When passing tokens (JWT) in Postman, the Authorization key must include Bearer, followed by the token, as shown in this screenshot:

Authorization

Authorization enforces API access privileges for the registered application. For more information, refer to Authenticate and Authorize.

Step 5: Send an HTTP Request

You're almost done. Now that your authentication and authorization are set, you're ready to send a test HTTP request. Continuing with our example, let's retrieve the activity having 'activityId' as 4224031, for which the complete cURL command is as follows:

curl -X GET "https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/activities/4224031" -u "<CLIENT_ID>@<INSTANCE_NAME>:<CLIENT_SECRET>"

OR

curl -X GET "https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/activities/4224031" -u "<CLIENT_ID>@<Alternate_INSTANCE_NAME>:<CLIENT_SECRET>"

Note:

In this example, we've used the 'activityId' value 4224031. For the cURL command to run successfully, ensure that you provide an activity ID that exists in your application.

This is how the request looks in Postman:

If the request is successful, you receive a response with a body. In this case, the response body contains the properties for the activity with 'activityId' as 4224031. If the request fails, and you're using cURL, review the response comments, adjust your request, and then try again. If you're using other clients, review the failure Status Codes, and then try again.


{
    "activityId": 4224031,
    "resourceId": "33001",
    "resourceInternalId": 3000001,
    "recordType": "regular",
    "status": "pending",
    "activityType": "4",
    "duration": 39,
    "travelTime": 30,
    "language": "en",
    "languageISO": "en-US",
    "timeZone": "(UTC-05:00) New York - Eastern Time (ET)",
    "timeZoneIANA": "America/New_York",
    "timeOfBooking": "2018-07-18 03:39:51",
    "timeOfAssignment": "2018-07-18 03:41:47",
    "firstManualOperation": "UNSCHEDULE",
    "firstManualOperationUser": "admin",
    "resourceTimeZone": "(UTC-05:00) New York - Eastern Time (ET)",
    "resourceTimeZoneIANA": "America/New_York",
    "resourceTimeZoneDiff": -300,
    "WO_TYPE": "5",
    "requiredInventories": {
        "links": [
            {
                "rel": "canonical",
                "href": "https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/activities/4224031/requiredInventories"
            }
        ]
    },
    "linkedActivities": {
        "links": [
            {
                "rel": "canonical",
                "href": "https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/activities/4224031/linkedActivities"
            }
        ]
    },
    "resourcePreferences": {
        "links": [
            {
                "rel": "canonical",
                "href": "https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/activities/4224031/resourcePreferences"
            }
        ]
    },
    "workSkills": {
        "links": [
            {
                "rel": "canonical",
                "href": "https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/activities/4224031/workSkills"
            }
        ]
    },
    "links": [
        {
            "rel": "canonical",
            "href": "https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/activities/4224031"
        },
        {
            "rel": "describedby",
            "href": "https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/metadata-catalog/activities"
        }
    ]
}

In a client such as Postman, the results are formatted and displayed in the Response section. For example, Postman lets you view the output in multiple formats. This screenshot shows the response in JSON.

Congratulations! Now you're ready to do more with your REST APIs.

Learn about common processes in the Use Cases section, such as how to receive events and download daily extract files.
Explore the Learn More section to understand advanced concepts like managing collections and accessing metadata.
Join the Oracle Developer Community, where you can share tips and advice with others.