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

Note:

You can integrate with Oracle B2C Service REST APIs through custom client applications developed using languages such as Java, JavaScript, Ruby, and so on.

Do NOT use the swagger.json available on Oracle Help Center to develop integration code for Oracle B2C Service REST APIs. This swagger.json is a sample created solely for documentation purposes and does not fully express the capabilities of the Oracle B2C Service REST APIs.

Step 2: Get Your Oracle B2C Service Account Info

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

REST Server URL. Typically, this is the URL of your Oracle B2C Service server. For example:
```
https://mysite.example.com
```
User name and password. An Oracle B2C Service user with permissions to access the REST resources you're using.

You can find the REST Server URL, user name, and password in the welcome email sent to your Oracle B2C 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:
```
https://<server>/<resource-path>
```
The <server> is the REST Server URL from Step 2, as in:
```
https://mysite.example.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 accounts resource:
```
/services/rest/connect/v1.4/accounts
```
Combine the REST Server URL and, in this example, the accounts resource path and your request URL is complete. For more information, see URL Path.
```
https://mysite.example.com/services/rest/connect/v1.4/accounts
```
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 a client such as Postman, you enter the user name and password on the Authorization tab. This screenshot shows how to specify this information in Postman:

You must also select the appropriate authorization type, such as basic, for your server. See Step 4 for details.
Set the custom headers. Include the custom header details using -H command as follows:
```
-H "OSvC-CREST-Application-Context:Accounts metadata"
```
For more information on custom headers, see Custom Headers.

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

curl -u "username:password" -X GET https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/accounts -H "osvc-crest-application-context: 1"

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

If you're an advanced REST user, but are reading our Quick Start anyway, you might want to 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, you can use one of the following authentication methods:

Basic authentication, which extracts the user name and password credentials from the HTTP header.
Session authentication, in which you can pass the Oracle B2C Service session token in the authorization header.
OAuth authentication, in which you can pass an OAuth token, supplied by an external identity provider (IdP), in the authorization header.

You need to select one of the methods. Let's look at our example using Basic authentication over SSL. To authenticate, you must submit the user name and password for your Oracle Cloud account. Typically, the user name and password are encoded in Base64 format, as in:

curl -H "authorization: Basic YWRtaW46" -X GET https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/accounts -H "osvc-crest-application-context: 1"

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://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/accounts -H "osvc-crest-application-context: 1"

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

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

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.

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, we want to get all the information about the structure of the account object in REST. You can do this using the following command in cURL:

curl -u "username:password" -X GET https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/accounts -H "osvc-crest-application-context: Retrieve Data"

This is how the request looks in Postman:

If your request for information about the account object is successful, you receive a response with a body similar to the following abbreviated example. If your 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.

{
    "name": "accounts",
    "links": [
        {
            "rel": "alternate",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/accounts",
            "mediaType": "application/schema+json"
        },
        {
            "rel": "describes",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts"
        },
        {
            "rel": "search",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts",
            "schema": {
                "type": "object",
                "properties": {
                    "q": {
                        "description": "Query parameter that allows searching by providing ROQL WHERE clause filtering",
                        "type": "string",
                        "format": "https://mysite.example.com/services/rest/connect/v1.4/accounts-search-form"
                    }
                }
            }
        },
        {
            "title": "Retrieve collection of accounts",
            "rel": "instances",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts",
            "mediaType": "application/json;type=collection",
            "method": "GET",
            "schema": {
                "type": "object",
                "properties": {
                    "offset": {
                        "$ref": "https://mysite.example.com/services/rest/connect/v1.4/schemas/OracleRESTStandard#/definitions/offsetQueryParam"
                    },
                    "limit": {
                        "$ref": "https://mysite.example.com/services/rest/connect/v1.4/schemas/OracleRESTStandard#/definitions/limitQueryParam"
                    },
                    "fields": {
                        "$ref": "https://mysite.example.com/services/rest/connect/v1.4/schemas/OracleRESTStandard#/definitions/fieldsQueryParam"
                    },
                    "orderBy": {
                        "$ref": "https://mysite.example.com/services/rest/connect/v1.4/schemas/OracleRESTStandard#/definitions/orderByQueryParam"
                    },
                    "totalResults": {
                        "$ref": "https://mysite.example.com/services/rest/connect/v1.4/schemas/OracleRESTStandard#/definitions/totalResultsQueryParam"
                    }
                }
            }
        },
        {
            "title": "Create an instance of accounts",
            "rel": "create",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts",
            "method": "POST",
            "schema": {
                "$ref": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/accounts#/definitions/singularResource",
                "required": [
                    "login",
                    "name",
                    "profile",
                    "staffGroup"
                ]
            }
        }
    ]
}

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 execute analytic reports and manage file attachments.
Explore the Learn More section to better manage collections and custom objects.
Join the Cloud Customer Connect forum, where you can share tips and advice with others.