Access Metadata

In the May 2016 release, the metadata catalog was enhanced to provide more useful information, such as whether REST resources and their fields are read-only (GET) or writeable (POST and PATCH), and supported query parameters.

Here are some ways to use the metadata catalog:

How You List the Metadata Catalog

Use the GET method with the following URI to list the metadata catalog:

https://your_site_interface/services/rest/connect/v1.4/metadata-catalog

Requesting the metadata catalog returns the list of resources, both standard and custom objects, for example:

{
    "items": [
    {
        "name": "accounts",
        "links": [
        {
            "rel": "alternate",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/accounts",
            "mediaType": "application/schema+json"
            },
        {
            "rel": "canonical",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/accounts",
            "mediaType": "application/json"
            },
        {
            "rel": "describes",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts"
            }
        ]
    },
    {
        "name": "analyticsReports",
        "links": [
        {
            "rel": "alternate",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/analyticsReports",
            "mediaType": "application/schema+json"
            },
        {
            "rel": "canonical",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/analyticsReports",
            "mediaType": "application/json"
            },
        {
            "rel": "describes",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/analyticsReports"
            }
        ]
    },
    ...
    {
        "name": "namedIDs",
        "links": [
        {
            "rel": "alternate",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/namedIDs",
            "mediaType": "application/schema+json"
            },
        {
            "rel": "canonical",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/namedIDs",
            "mediaType": "application/json"
            },
        {
            "rel": "describes",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/namedIDs"
            }
        ]
    },
    {
        "name": "queryResults",
        "links": [
        {
            "rel": "alternate",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/queryResults",
            "mediaType": "application/schema+json"
            },
        {
            "rel": "canonical",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/queryResults",
            "mediaType": "application/json"
            },
        {
            "rel": "describes",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/queryResults"
            }
        ]
    }
    ],
    "links": [
    {
        "rel": "canonical",
        "href": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog"
        },
    {
        "rel": "describedby",
        "href": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog",
        "mediaType": "application/schema+json"
        }
    ]
}

How You Retrieve Metadata for a Specific Resource

To retrieve detailed metadata for a resource, use a GET request against its corresponding metadata-catalog resource:

https://your_site_interface/services/rest/connect/version/metadata-catalog/resource

with the header listed in the following table:

Header Value
Accept application/schema+json

Note:

Because detailed metadata-catalog requests require an Accept header, it's recommended to use a REST client such as Postman or Advanced Rest Client for such requests.

Request URI example

For example, to retrieve the metadata for the opportunities resource, use a GET request with the following syntax and an Accept header:

https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/accounts

Response body example

Boolean attributes for opportunity fields show the available operations on those fields:

  • isAvailableForGET
  • isAvailableForPOST
  • isAvailableForPATCH

Supported query parameters are listed in the instances links at the end of the response under links.

{
    "$schema": "https://mysite.example.com/services/rest/connect/v1.4/schemas/ConnectOracleRESTStandard#",
    "title": "Resource Schema",
    "description": "Schema representing a typed resource",
    "type": "object",
    "allOf": [
        {
            "$ref": "https://mysite.example.com/services/rest/connect/v1.4/schemas/ConnectOracleRESTStandard#/definitions/collectionPagedResource"
        }
    ],
    "definitions": {
        "singularResource": {
            "allOf": [
                {
                    "$ref": "https://mysite.example.com/services/rest/connect/v1.4/schemas/ConnectOracleRESTStandard#/definitions/resourceMeta"
                }
            ],
            "type": "object",
            "description": "An account generated for a staff member in the system. Staff accounts are used by CSRs, sales agents, site administrators, etc.",
            "name": "accounts",
            "isMenu": false,
            "releaseIntroduced": "15.5",
            "properties": {
                "id": {
                    "description": "Primary key identifier",
                    "releaseIntroduced": "15.5",
                    "isDeprecated": false,
                    "isEnumerable": false,
                    "label": "ID",
                    "nullable": false,
                    "isAvailableForGET": true,
                    "isAvailableForPOST": false,
                    "isAvailableForPATCH": false,
                    "minimum": 1,
                    "maximum": 9223372036854775807,
                    "usedAsName": false,
                    "type": "integer"
                },
                "lookupName": {
                    "description": "Name used to lookup this object",
                    "releaseIntroduced": "15.5",
                    "isDeprecated": false,
                    "isEnumerable": false,
                    "label": "LookupName",
                    "nullable": false,
                    "isAvailableForGET": true,
                    "isAvailableForPOST": false,
                    "isAvailableForPATCH": false,
                    "maxLength": 255,
                    "usedAsName": false,
                    "type": "string"
                },
                "createdTime": {
                    "description": "Creation date and time.  Read-only",
                    "releaseIntroduced": "15.5",
                    "isDeprecated": false,
                    "isEnumerable": false,
                    "label": "CreatedTime",
                    "nullable": false,
                    "isAvailableForGET": true,
                    "isAvailableForPOST": false,
                    "isAvailableForPATCH": false,
                    "minimumDateTime": "1970-01-02T00:00:00.000Z",
                    "maximumDateTime": "2038-01-17T23:59:59.000Z",
                    "usedAsName": false,
                    "type": "string"
                },
                ...

                "displayName": {
                    "description": "Display name",
                    "releaseIntroduced": "15.5",
                    "isDeprecated": false,
                    "isEnumerable": false,
                    "label": "DisplayName",
                    "nullable": true,
                    "isAvailableForGET": true,
                    "isAvailableForPOST": true,
                    "isAvailableForPATCH": true,
                    "pattern": "^[^\n]*$",
                    "minLength": 1,
                    "maxLength": 80,
                    "usedAsName": false,
                    "type": [
                        "string",
                        "null"
                    ]
                },
                ...

                "staffGroup": {
                    "description": "Group to which the staff member is assigned",
                    "releaseIntroduced": "15.5",
                    "isDeprecated": false,
                    "isEnumerable": true,
                    "label": "StaffGroup",
                    "nullable": false,
                    "isAvailableForGET": true,
                    "isAvailableForPOST": true,
                    "isAvailableForPATCH": true,
                    "usedAsName": false,
                    "type": "object",
                    "$ref": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/namedIDs/accounts/staffGroup"
                }
            }
        }
    },
    "properties": {
        "items": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "id": {
                        "$ref": "#/definitions/singularResource/properties/id"
                    },
                    "lookupName": {
                        "$ref": "#/definitions/singularResource/properties/lookupName"
                    },
                    "createdTime": {
                        "$ref": "#/definitions/singularResource/properties/createdTime"
                    },
                    "updatedTime": {
                        "$ref": "#/definitions/singularResource/properties/updatedTime"
                    }
                }
            }
        }
    },
    "links": [
        {
            "rel": "self",
            "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"
                ]
            }
        }
    ]
}

How You Retrieve Request Syntax for a Resource

To retrieve the syntax for requests against a resource, use a GET request with the following syntax:

https://your_site_interface/services/rest/connect/version/metadata-catalog/resource#/definitions

Note:

Request syntax isn't available for special resources, such as queryResults, NamedIDs, and NamedIDHierarchies.

Request URI example

For example, to retrieve the request syntax for the incidents resource, use the following GET request:

https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/accounts#/definitions

Response body example

The following are returned:

  • Link to ROQL object query syntax
  • GET request syntax (if available), as well as links to definitions for supported query parameters
  • POST request syntax (if available), as well as parameters and required fields
            "type": "object",
            "description": "An account generated for a staff member in the system. Staff accounts are used by CSRs, sales agents, site administrators, etc.",
            "name": "accounts",
            "isMenu": false,
            "releaseIntroduced": "15.5",

    "links": [
        {
            "rel": "self",
            "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"
                ]
            }
        }
    ]
}