REST API for Oracle Fusion Cloud Student Management

Quick Start

You can make many types of HTTP requests using Oracle Applications Cloud REST APIs. You can make requests to view, create, update, or delete records. But first, send a simple REST HTTP request to know the structure of an academicGroups object.

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. For details, see Security Reference for Common Features.

Review opt-in requirements. Some resources or their attributes might be associated with features that require opt-in before you can use them. Make sure to enable these 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. The examples on these pages use cURL. But, cURL isn't the only tool you can use. To help you choose one, see Work with your REST API Client.

Step 2: Get Your Oracle Student Management Account Info

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

REST Server URL. Typically, the URL of your Oracle Cloud service. For example, https://servername.fa.us2.oraclecloud.com.
User name and password. An Oracle Cloud service user with permissions to access the resources you're using.

You can find the REST Server URL, user name, and password in the welcome email sent to your Oracle Cloud service administrator.

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, like this: https://server/resource-path, where
- server is the REST Server URL from Step 2, for example, https://servername.fa.us2.oraclecloud.com.
- resource-path is the relative path or endpoint to the resource you're working with. You can pick any endpoint from the list on All REST Endpoints. For example, if you're interested in the academic groups resource, the resource-path is/fscmRestApi/resources/11.13.18.05/academicGroups. However, some resources or their attributes might be associated with features that require opt-in before you can use them.
Combine the REST Server URL and resource path, and your request URL is complete. In this example, it is https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/academicGroups. For more information, see URL Paths.
Provide your account information. Include your user name and password (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 username:password

In clients, such as Postman, you supply these credentials through their Authorization tab. The following screenshot shows how to specify this information in the Postman client.

In REST API clients that work through browser extensions or add-ons, such as RESTClient for Mozilla Firefox, you supply these credentials through the Authorization option, as shown in the following image:

Select the appropriate authorization type (see Step 4).
Set the media type. Media type defines the structure of the HTTP payloads exchanged between the server and the client. For example, if you're using cURL, you can specify a resource item media type using the header -H command as follows: -H 'Content-Type: application/vnd.oracle.adf.resourceitem+json'

For more on media types, see Supported Media Types.

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

curl -u username:password \
 -X GET https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/academicGroups/describe \
 -H 'Content-Type: application/vnd.oracle.adf.resourceitem+json'  | json_pp

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

If you're an advanced REST user, but are reading this page anyway, you might want to set the REST Framework or configure Cross-Origin Resource Sharing (CORS) now. Otherwise, you're ready to move on to Step 4.

Step 4: Authenticate and Authorize

Now that you've configured the client with a complete request URL, it's time to authenticate and authorize yourself. Authentication proves that your credentials are genuine, and authorization allows you to apply your access privileges.

Authentication

To make sure data access over a network is secure, Oracle Applications Cloud REST APIs use a global Oracle Web Services Manager (OWSM) security policy called Multi Token Over SSL RESTful Service Policy (oracle/multi_token_over_ssl_rest_service_policy). This security policy enforces the following authentication standards:

Basic authentication over SSL (Secure Socket Layer), which extracts the user name and password credentials from the HTTP header.
SAML 2.0 bearer token in the HTTP header over SSL, which extracts a SAML 2.0 bearer assertion (XML security token).
Use JSON Web Token for Authorization, which extracts the user name from the Jason Web Token.

You must select one of the standards. For example, if you use Basic authentication over SSL, submit the user name and password for your Oracle Cloud account. Typically, the user name and password are encoded in Base-64 format, as follows:

curl \
-X GET https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/academicGroups/describe \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-H 'Content-Type: application/vnd.oracle.adf.resourceitem+json'

Alternatively, you can use the -u cURL option to pass the user name and password for your Oracle Cloud account, as in this example:

curl -u username:password \
-X GET https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/academicGroups/describe \
-H 'Content-Type: application/vnd.oracle.adf.resourceitem+json'

Your authorization and authentication information gets passed in the Authorization key of the request header.

When passing tokens (SAML or JWT) in Postman, the Authorization key must include Bearer, followed by the token, as shown in this screenshot:

Authorization

Authorization enforces access privileges by service role. Access to an object determines access to a resource. So, make sure that your user has the proper role.

For additional details, including a list of specific roles for accessing a resource, see Security Reference for Student Management and Security Reference for Common Features.

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. This example shows you how to get a list of all academic groups through REST. You can do this by using the describe action in cURL:

curl -u username:password \
 -X GET https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/academicGroups/describe \
-H 'Content-Type: application/vnd.oracle.adf.resourceitem+json'

The following image shows a request in the Postman client.

If your request for information about the Academic Groups object is successful, you receive a response with a body similar to the following abbreviated example.

{
  "Resources" : {
    "academicGroups" : {
      "discrColumnType" : false,
      "attributes" : [ {
        "name" : "AcademicGroupId",
        "type" : "integer",
        "updatable" : false,
        "mandatory" : true,
        "queryable" : true,
        "allowChanges" : "never",
        "precision" : 18,
        "hasDefaultValueExpression" : true,
        "title" : "Curriculum ID"
      }, {
        "name" : "CurriculumName",
        "type" : "string",
        "updatable" : false,
        "mandatory" : true,
        "queryable" : true,
        "allowChanges" : "never",
        "precision" : 50,
        "title" : "Name",
        "maxLength" : "50"
      }, 
	  ...
       ],
      "collection" : {
        "rangeSize" : 25,
        "finders" : [ {
          "name" : "AcademicGroupIdFinder",
          "title" : "FindByAcademicGroupId",
          "attributes" : [ {
            "name" : "BindAcademicGroupId",
            "type" : "integer",
            "updatable" : true,
            "required" : "Optional",
            "queryable" : false,
            "allowChanges" : "always"
          } ]
        }, {
          "name" : "PrimaryKey",
          "attributes" : [ ]
        } ],
        "links" : [ {
          "rel" : "self",
          "href" : "https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/academicGroups",
          "name" : "self",
          "kind" : "collection"
        } ],
        "actions" : [ {
          "name" : "get",
          "method" : "GET",
          "responseType" : [ "application/vnd.oracle.adf.resourcecollection+json", "application/json" ]
        } ]
      },
      "item" : {
        "links" : [ {
          "rel" : "lov",
          "href" : "https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/academicGroups/{id}/lov/AcademicInstitutionLOV",
          "name" : "AcademicInstitutionLOV",
          "kind" : "collection"
        }, {
          "rel" : "lov",
          "href" : "https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/academicGroups/{id}/lov/AcademicLevelLOV",
          "name" : "AcademicLevelLOV",
          "kind" : "collection"
        },  
		...      
}

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

If your request fails, and you're using cURL, review the response comments, modify your request, and try again. If you're using other clients, see the failure Status Codes, and try again.

Note:

For any CRUD action for a resource that has both the auto-generated unique ID and a user-defined identifier, use only one of these parameters in the request payload. If you use both, the behavior isn't specified and may change without notice.

For example, assume that the calendarEvent resource includes a foreign key to an announcement resource. Suppose the announcement resource has a unique identifier AnnouncementId (300100111705686) and an alternative, user-defined identifier called AnnouncementNumber (ANN_332708). When you create a calendarEvent, or update a calendarEvent reference to an announcement, do not use both the AnnouncementId and the AnnouncementNumber parameters in the same request payload.

Now you're ready to do more with the REST APIs. Join the Oracle Developer Community, where you can share tips and advice with others.